# 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.