SkjölunFyrir forritara

Webhooks

Kling sendir undirritaðan webhook á þjóninn þinn þegar greiðsla, krafa eða áskrift breytist. Hvernig þú skráir endapunkt, hvaða atburðir eru til, hvernig þú staðfestir X-Kling-Signature hausinn og hvernig endurtekningar virka.

Webhook er beiðni sem Kling sendir á þjóninn þinn þegar eitthvað gerist, til dæmis þegar greiðsla fer í gegn. Afgreiddu pantanir út frá webhooks, ekki út frá vafra viðskiptavinarins: vafrinn getur lokast áður en hann kemst aftur á síðuna þína.

Skráðu endapunkt

Í stjórnborðinu opnar þú Tilkynningar og bætir við webhook með slóðinni þinni og atburðunum sem þú vilt fá. Eða notaðu 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",
    "config": { "url": "https://example.is/api/webhooks/kling" },
    "event_subscriptions": ["checkout.session.completed", "payment_intent.captured"]
  }'

Kling býr til undirritunarlykil og skilar honum í config.secret; hann sést líka í stjórnborðinu. Slóðin þarf að vera aðgengileg af netinu. npx @klingis/cli init getur gert þetta allt fyrir þig og skrifað lykilinn í .env.local sem KLING_WEBHOOK_SECRET.

Prófun og raunumhverfi hafa aðskilda endapunkta og lykla.

Atburðir

Atburður	Hvenær
`checkout.session.completed`	Viðskiptavinur lauk greiðsluferli
`payment_intent.captured`	Upphæðin var innheimt: kortagreiðsla, eða krafa sem var greidd
`payment_intent.failed`	Greiðsla mistókst
`payment_intent.refunded`	Greiðsla var endurgreidd
`claim.created`, `claim.paid`	Krafa í heimabanka var stofnuð eða greidd
`subscription.created`, `subscription.activated`, `subscription.updated`, `subscription.canceled`	Breytingar á áskrift
`subscription.renewed`	Endurnýjun var rukkuð
`subscription.trial_ended`	Prufutíma lauk
`subscription.payment_failed`, `subscription.payment_retry_failed`, `subscription.payment_recovered`	Endurnýjun mistókst, ný tilraun mistókst, eða ný tilraun tókst

Beiðnin

Kling sendir POST með JSON:

json

{
  "id": "evt_...",
  "type": "payment_intent.captured",
  "created_at": "2026-10-01T12:00:00.000Z",
  "data": { "id": "pi_..." },
  "merchant_id": "...",
  "environment": "test"
}

Í data er hluturinn sem atburðurinn snýst um, fyrst id hans. Hausar: X-Kling-Signature, X-Kling-Event (tegund atburðar) og X-Kling-Delivery-Id.

Staðfestu undirritunina

X-Kling-Signature er sha256= og á eftir HMAC-SHA256 af hráum meginmáli beiðninnar, í hex, með undirritunarlyklinum þínum. Reiknaðu hana af nákvæmlega þeim bætum sem bárust, áður en JSON er þáttað:

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);
}

Hafnaðu beiðninni með 401 ef hún passar ekki.

Endurtekningar

Svaraðu með 2xx innan 30 sekúndna. Allt annað telst misheppnað og Kling reynir aftur eftir 1 mínútu, 5 mínútur, 30 mínútur og 2 klukkustundir (fimm tilraunir alls). Tilvísunum (redirects) er ekki fylgt. Láttu meðhöndlunina þola að sami atburður berist tvisvar: notaðu id atburðarins til að sleppa tvíteknum.

POST /v1/notification-channels/test-webhooks sendir debug.check atburð á endapunktinn svo þú getir prófað hann.

Í þróun á eigin vél

npx @klingis/cli listen --forward http://localhost:3000/api/webhooks/kling sækir prófunaratburðina þína og framsendir á þjóninn á vélinni þinni, án opinberrar slóðar. Framsendir atburðir eru ekki undirritaðir, svo slepptu staðfestingunni fyrir þá í þróun.

Skoða sem markdown