Webhooks
Få beskjed når noe skjer, og verifiser at beskjeden kommer fra KETL.
Abonner
Opprett en webhook med POST /v1/webhooks. Send url og hendelser i body. Svaret har secret i data. Lagre den trygt, for den vises ikke senere. Hendelsene du kan velge mellom, står i webhooks-delen av OpenAPI-spesifikasjonen. Live-webhooks lager du med innlogging i utviklerportalen, og en testnøkkel (sk_test_) lager test-webhooks.
Verifiser signaturen
Hver leveranse har headeren X-Ketl-Signature med verdien sha256=<hex>. Det er HMAC-SHA256 av rå body, med secret som nøkkel.
Bruk body slik du mottok den. Les du den som JSON og skriver den ut på nytt, stemmer ikke signaturen.
Tidsstempelet leser du fra headeren X-Ketl-Timestamp. Det er samme verdi som tidspunkt i body, og tidspunkt er med i det som signeres. Avvis leveranser der tidsstempelet er eldre enn 5 minutter.
Under nøkkelrotasjon kommer også X-Ketl-Signature-Forrige, signert med forrige nøkkel. Godta en av dem.
Leveransen har også X-Ketl-Hendelse (hendelseskoden), X-Ketl-Attempt (forsøksnummer, fra 1), X-Ketl-Event-Id (samme verdi ved hvert forsøk) og X-Ketl-Delivery-Id (unik per leveranse). Dedupliser på X-Ketl-Event-Id.
Eksempelet viser beregningen. Bruk sammenligning i konstant tid i koden din.
# body.json er rå body, uendret. SIGNATUR er verdien i X-Ketl-Signature.
forventet="sha256=$(openssl dgst -sha256 -hmac "$HEMMELIGHET" < body.json | sed 's/^.*= //')"
[ "$forventet" = "$SIGNATUR" ] && echo "Signaturen stemmer"Retry og ny sending
Svar 2xx innen 10 sekunder.
Ved 5xx, 429, timeout eller nettverksfeil prøver vi igjen etter ca. 5 min, 30 min, 2 t og 24 t. Det blir maks 5 forsøk over ca. 26 timer.
Andre 4xx-svar er permanente feil og gir ikke nye forsøk.
En leveranse som er gitt opp, havner i dead-letter-køen. List den med GET /webhooks/{id}/dlq.
Send en leveranse på nytt med POST /webhooks/dlq/{id}/resend, der id er leveranseId fra oppføringen. Den nye leveransen har samme X-Ketl-Event-Id, så dedupliseringen din virker også her.
Leveringslogg
Hvert leveringsforsøk logges. Hent de 50 siste med GET /webhooks/{id}/logg, der id er webhook-ID-en.