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:
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.completedarrives only once it is paid, withdata.payment_status: "paid". - Classic ("With a payment window", and Landsbanki claims):
checkout.session.completedarrives when the claim is issued, withdata.payment_status: "awaiting_claim", before any money has arrived. Fulfil on thepayment_intent.capturedwhosedata.idmatchesdata.payment_intent_idfromcheckout.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.renewedfires for each paid card renewal, including one paid by a successful retry. That retry also sendssubscription.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.capturedwithdata.subscription_id;subscription.activatedcomes before the charge; - a period with nothing to charge (a free plan, or a discount that covers the whole period);
bank_claimsubscriptions.
- the first charge after a free trial. That one is a
bank_claimsubscriptions renew by issuing a krafa each period:claim.createdwhen it is issued, thenclaim.paidandpayment_intent.capturedwhen it is paid.claim.createdandclaim.paidcarrysubscriptionId,billingReason(subscription_cyclefor a renewal),periodStartandperiodEnd; thatpayment_intent.capturedcarriessubscription_id,billing_reason,period_startandperiod_end. There is nosubscription.payment_failedand no automatic retry for a krafa.subscription.canceledfires when a cancellation at the end of the period is requested (the subscription is stillactive, withcancel_at_period_end: true) and again when it actually ends. Check the subscription'sstatusbefore you revoke access: it iscanceledonce 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, thensubscription.canceled.
The request
Kling sends a POST with a JSON body:
{
"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:
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.