Webhooks — bygg en mottaker NO
Verifiser signaturen, håndter gjentatte leveringer og følg opp hendelser fra Kaduno.
Et abonnement tilhører én butikk. Opprett det under Webhooks i admin eller med
POST /api/v1/webhooks og en REST-nøkkel med webhooks:manage.
Hent hendelsestypene fra GET /api/v1/webhooks/events.
Abonnement
Eksempel på JSON-kropp ved opprettelse:
{
"name": "Ordre til ERP",
"url": "https://erp.example.com/webhooks/kaduno",
"events": ["order.placed", "order.confirmed"],
"secret": "REPLACE_WITH_A_RANDOM_SIGNING_SECRET"
}Erstatt eksempeldomenet og hemmeligheten. REST krever ikke secret, men uten den
signeres ikke leveringer. Sett en tilfeldig hemmelighet på 16–256 tegn, lagre den
hos mottakeren og kontroller signaturen før data behandles.
Verifiser den rå kroppen
Headeren X-Webhook-Signature inneholder sha256= etterfulgt av en HMAC-SHA256
i hex. Beregn signaturen over de nøyaktige bytene dere mottok. Ikke parse og
serialiser JSON før verifisering.
import { createHmac, timingSafeEqual } from 'node:crypto';
export function verifyWebhook(rawBody, signature, secret) {
if (!Buffer.isBuffer(rawBody) || typeof signature !== 'string' || !secret) {
return false;
}
const expected = Buffer.from(
'sha256=' + createHmac('sha256', secret).update(rawBody).digest('hex'),
);
const received = Buffer.from(signature);
return expected.length === received.length && timingSafeEqual(expected, received);
}Koble eksemplet til rammeverkets støtte for rå forespørselskropp. En manglende eller feil signatur skal avvises. Dette eksemplet verifiserer bare signaturen; kø, lagring og tilgangskontroll må implementeres i mottakeren.
Behandle hver levering én gang
Kroppen inneholder event, payload, deliveryId, occurredAt og timestamp.
X-Webhook-Delivery er samme ID som deliveryId, og beholdes ved nye forsøk.
- Verifiser signaturen.
- Kontroller at hendelsen er en dere forventer.
- Lagre leverings-ID og arbeid i en varig kø eller transaksjon. En unik nøkkel på leverings-ID beskytter mot to samtidige forsøk.
- Svar med
2xxnår leveringen er trygt tatt imot. En allerede mottatt levering kan kvitteres uten å utføre arbeidet igjen.
occurredAt er hendelsens tidspunkt. timestamp er tidspunktet for det enkelte
leveringsforsøket. Payload varierer med hendelsen: form.submitted og
quote.submitted inneholder identifikatorer, ikke skjemafelter eller kontaktdata.
Hent resten med en autorisert API-forespørsel når det trengs.
Når mottakeren ikke svarer
Et tidsavbrudd eller et svar utenfor 2xx utløser nye forsøk, innenfor abonnementets
konfigurerte antall. retryCount teller alle forsøk, inkludert det første.
Ventetiden øker fra 30 sekunder, med et tak på 10 minutter mellom forsøkene.
Kontroller leveringsloggen i admin. En levering som har brukt opp forsøkene, markeres som feilet og kan prøves igjen derfra. Behold dedupliseringen også ved manuelle nye forsøk.
Se API og webhooks — kom i gang for nøkler, scopes og API-referanse.
Prøv signaturkontrollen uten å koble til butikken
Kjør den lokale utviklerøvelsen med syntetiske data. Den viser både endret råkropp og hvorfor en signatur alene ikke stopper en gjentatt levering. Ingen API-nøkkel eller virkelig ordre er nødvendig.