Utviklere

Webhooks (utvikler)

Motta Itemra-webhooks riktig: headere, HMAC-verifisering, idempotent konsum, nye forsøk og replay.

Leveransen

Abonnementer forvaltes i Innstillinger → Webhooks eller via /v1/webhooks. Hver leveranse POST-er standardkonvolutten (se hendelsesstrømmen — samme form, samme katalog) med disse headerne:

X-Itemra-Webhook-Id: evt_01…
X-Itemra-Webhook-Delivery-Id: whdel_01…
X-Itemra-Webhook-Event: stock.changed
X-Itemra-Webhook-Timestamp: 1783937730
X-Itemra-Webhook-Signature: v1=<lowercase-hex-hmac>

Verifiser før dere stoler

1. Les den eksakte rå UTF-8-kroppen før noen JSON-parsing.
2. Avvis tidsstempler utenfor et fem-minutters replay-vindu.
3. Sett sammen <unix-tidsstempel>.<rå-kropp> — ingen omformatering.
4. Beregn HMAC-SHA256 med abonnementets signeringshemmelighet.
5. Sammenlign mot v1=<hex-digest> i konstant tid.
6. Registrer X-Itemra-Webhook-Id; returner 2xx for en ID dere allerede har behandlet.

Hemmeligheten vises én gang ved opprettelse/rotasjon — legg den i en hemmelighetsforvalter og logg den aldri. Rotasjon gjelder leveranser opprettet etterpå; pågående forsøk beholder hemmeligheten de ble utstedt med.

Konsumer idempotent, svar raskt

Levering er minst-én-gang: duplikater er normalt, rekkefølge garanteres ikke — dedupliser på hendelses-ID, bruk occurredAt for domenetid, og hent gjeldende tilstand fra API-et når rekkefølge betyr noe. Returner 2xx raskt og behandle asynkront; trege mottakere prøves på nytt med økende venting.

Nye forsøk, feilkø, replay

Ikke-2xx, tidsavbrudd og nettverksfeil prøves på nytt med begrenset eksponentiell venting; uttømte leveranser havner i feilkøen og forblir synlige i leveringsloggen, der replay sender dem på nytt etter at mottakeren er rettet. Testleveranser kjører samme signering og arbeidsløype som produksjonshendelser — bruk dem til å verifisere hele kjeden før dere går live, og varsle på feilkø i produksjon.