Topics

DocsDeveloper reference

Webhooks

Kling sends a signed webhook to your server when a payment, claim or subscription changes. How to register an endpoint, which events exist, when an order is paid, how to verify the X-Kling-Signature header and how retries work.

A webhook is a request Kling sends to your server when something happens, such as a payment going through. Use webhooks to fulfil orders, not the customer's browser: the browser can close before it gets back to your site.

Register an endpoint

In the dashboard, open Developers → Webhooks and add a webhook with your URL and the events you want. Or use the API:

bash
curl -X POST https://api.kling.is/v1/notification-channels \
  -H "Authorization: Bearer $KLING_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "webhook",
    "name": "My shop",
    "config": { "url": "https://example.is/api/webhooks/kling" },
    "event_subscriptions": ["checkout.session.completed", "payment_intent.captured"]
  }'

type, name, config.url and at least one event in event_subscriptions are required. Kling generates a signing secret and returns it in config.secret; the dashboard shows it too. The URL must be public and use https://. Keep the secret on your server, for example as KLING_WEBHOOK_SECRET.

Test and live have separate endpoints and secrets.

Events

Event When
checkout.session.completed A checkout session finished. For a card payment the money has been taken. For a bank claim it can arrive before the money: see When an order is paid.
payment_intent.captured Money was taken: a card payment (online or in person), or a bank claim paid in full. An amount of 0 is a card verification (a card was saved or updated), not a sale.
payment_intent.failed A payment attempt failed: a declined card at checkout (the customer can try again), or a failed subscription charge or retry.
payment_intent.refunded A payment was refunded, fully or in part. data.amount is this refund and data.partial says whether some is left.
claim.created An online bank claim (krafa) was issued.
claim.paid A bank claim was paid in full.
subscription.created A subscription was created.
subscription.trial_ended A free trial ended.
subscription.activated The subscription became active after its trial. Sent before the first charge, so it does not mean paid.
subscription.updated A subscription changed: reactivated, new card, discount added or removed.
subscription.product_change_scheduled A move to another product was requested. data.product_id is the new product and data.effective_at says when the switch takes effect, at the start of the next period.
subscription.product_changed The subscription moved to the new product at the start of a new period. The renewal that follows charges the new product's price.
subscription.canceled A cancellation was requested, or the subscription ended. See Subscription events.
subscription.renewed A card renewal was paid.
subscription.payment_failed A card renewal, or the first charge after a trial, failed. data.next_retry_at is the next attempt, or null when there is none.
subscription.payment_retry_failed A retry failed. data.next_retry_at is null after the last one, and the subscription is canceled.
subscription.payment_recovered A retry succeeded.
subscription.paused, subscription.resumed Collection was paused or resumed.
subscription.cycle_skipped A billing period passed without a charge because collection is paused.

Kling has no invoice events.

When an order is paid

Fulfil each order once, and make fulfilment idempotent per order, for example on the checkout session ID or your own order ID in metadata. The event id only protects you against the same event arriving twice: checkout.session.completed and payment_intent.captured for the same order are two different events with different ids, so a handler that fulfils on both ships a card order twice.

Card: checkout.session.completed means the order is paid.

Bank claim (krafa): a checkout offers every payment method you have switched on, including bank claims once they are activated, even if your code never mentions them. Create the session with payment_method_type: "card" for cards only, or "bank_claim" for claims only (ISK). How a krafa checkout completes depends on the mode:

  • Instant (the default with Kling's claims provider): the claim is due today and the checkout waits about 5 minutes for the customer to pay it in their bank. checkout.session.completed arrives only once it is paid, with data.payment_status: "paid".
  • Classic ("With a payment window", and Landsbanki claims): checkout.session.completed arrives when the claim is issued, with data.payment_status: "awaiting_claim", before any money has arrived. Fulfil on the payment_intent.captured whose data.id matches data.payment_intent_id from checkout.session.completed. That event does not carry the session's metadata, so keep the link between the two yourself.

In short: treat checkout.session.completed as paid unless data.payment_status is "awaiting_claim". Card completions have no payment_status field.

If you poll GET /v1/checkout-sessions/{id} instead, check payment_status === "paid" (or "no_payment_required" for a zero-amount session), not status === "complete".

Subscription events

  • subscription.renewed fires for each paid card renewal, including one paid by a successful retry. That retry also sends subscription.payment_recovered, so handle the renewal once. It does not fire for:
    • the first charge after a free trial. That one is a payment_intent.captured with data.subscription_id; subscription.activated comes before the charge;
    • a period with nothing to charge (a free plan, or a discount that covers the whole period);
    • bank_claim subscriptions.
  • bank_claim subscriptions renew by issuing a krafa each period: claim.created when it is issued, then claim.paid and payment_intent.captured when it is paid. claim.created and claim.paid carry subscriptionId, billingReason (subscription_cycle for a renewal), periodStart and periodEnd; that payment_intent.captured carries subscription_id, billing_reason, period_start and period_end. There is no subscription.payment_failed and no automatic retry for a krafa.
  • subscription.canceled fires when a cancellation at the end of the period is requested (the subscription is still active, with cancel_at_period_end: true) and again when it actually ends. Check the subscription's status before you revoke access: it is canceled once it has ended.
  • A hard decline (for example a card reported lost, or a closed account) cancels the subscription at once, with no more retries: a failed event with next_retry_at: null, then subscription.canceled.

The request

Kling sends a POST with a JSON body:

json
{
  "id": "5b0c6f0e-2d7a-4f43-9a51-3f0b8f6c1e2d",
  "type": "payment_intent.captured",
  "created_at": "2026-10-01T12:00:00.000Z",
  "data": { "id": "9d2e4b7a-1c3f-4e8a-b6d5-0a7f2c9e4b11", "amount": 4990 },
  "merchant_id": "...",
  "environment": "test"
}

data.id is the ID of the object the event is about: the payment intent, checkout session, claim or subscription. The other fields in data depend on the event and on how the payment was made, and their casing is mixed (for example checkoutSessionId next to subscription_id). Fetch the object from the API when you need its current state. IDs are UUIDs. Amounts are in the currency's smallest unit: ISK has none (4990 is 4.990 kr), EUR and USD are in cents (4990 is €49.90).

The fields most integrations use:

Event Fields in data
checkout.session.completed payment_intent_id, customer_id, subscription_ids (a list, empty when there is none), payment_status (bank claims only), metadata, custom_fields
payment_intent.captured amount, metadata, and subscription_id when Kling charged a subscription (a renewal, or the first charge after a trial or through the API)
subscription.renewed payment_intent_id, amount, period_start, period_end

Headers: X-Kling-Signature, X-Kling-Event (the event type) and X-Kling-Delivery-Id.

Verify the signature

X-Kling-Signature is sha256= followed by the hex HMAC-SHA256 of the raw request body, keyed with your signing secret. Compute it over the exact bytes you received, before parsing the JSON:

typescript
import crypto from "node:crypto";

export function verifyKlingSignature(rawBody: string, header: string | null, secret: string): boolean {
  if (!header) return false;
  const expected = "sha256=" + crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  const a = Buffer.from(expected);
  const b = Buffer.from(header);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Reject the request with a 401 if it doesn't match.

Retries

Answer with any 2xx status within 30 seconds. Anything else counts as a failure and Kling tries again after 1 minute, 5 minutes, 30 minutes and 2 hours (five attempts in all). Redirects are not followed: a 3xx fails the delivery without retrying. Events can arrive out of order, and the same event can arrive more than once: use the event id to skip duplicates.

POST /v1/notification-channels/test-webhooks sends a debug.check event to your endpoint so you can test it.

Local development

Kling only delivers webhooks to a public URL, so a server on localhost can't receive them directly. Use a tunnelling tool, such as ngrok or Cloudflare Tunnel, that gives your local server a public HTTPS address, and register that address as a webhook in test mode. Events then reach your machine signed, exactly as they will in production, so your signature check runs as it should.

To check the connection without making a payment, POST /v1/notification-channels/test-webhooks sends a signed debug.check event, once and without retries, to every enabled webhook in your API key's environment. Its data has a message and no id. Or make a test payment with a test card and watch the real events arrive. When you are done, remove the tunnel's webhook, or switch it off, in the dashboard.

View as markdown