Webhooks
Het interessante is wat er gebeurt wanneer de aflevering mislukt
Ondertekening, retries, volgorde en idempotentie zijn het hele contract. Een integratie die alleen het gelukkige pad afhandelt is niet af; die is niet begonnen.
- Levering
- Ten minste eenmaal
- Ondertekend
- Over de ruwe body
- Retries
- Exponentiële backoff
Definition
Hoe werken paspoortwebhooks?
CirculeID stuurt een ondertekende callback naar uw endpoint wanneer een paspoort, gebeurtenis of credential verandert. Levering is ten minste eenmaal met exponentiële backoff, dus handlers moeten de handtekening verifiëren, herhaalde leveringsidentificatoren als no-op behandelen, en de huidige staat via de API teruglezen voordat zij handelen.
Treat a payload as a notification, not as the record. That single habit removes the entire class of bug where a delayed retry overwrites newer data with older data.
Gebeurtenissen
Waarop u zich kunt abonneren
| Event | Fires when | Typical handler |
|---|---|---|
| passport.created | A passport is issued against an identifier | Print or encode the data carrier |
| passport.updated | The record changes materially | Re-read state; refresh a cached storefront view |
| event.recorded | An EPCIS event is appended to an object | Advance an internal workflow |
| credential.issued | A supplier signs a claim against your product | Clear the compliance gap for that field |
| credential.revoked | An issuer withdraws a claim | Re-open the gap; review anything that relied on it |
| passport.gap_detected | A delegated act change leaves a field unmet | Raise it to the compliance owner |
Verificatie
Verifieer voordat u parseert
import { createHmac, timingSafeEqual } from 'node:crypto';
export function verify(rawBody, header, secret) {
const [ts, signature] = parseHeader(header);
// Reject replays before doing any work.
if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
const expected = createHmac('sha256', secret)
.update(`${ts}.${rawBody}`) // raw body, exactly as received
.digest();
// Constant-time: a fast reject leaks the signature one byte at a time.
return timingSafeEqual(Buffer.from(signature, 'hex'), expected);
}Contract
Wat het platform garandeert
Ondertekende payloads
HMAC over de ruwe body met een geheim per endpoint, plus een tijdstempel.
Levering ten minste eenmaal
De eerlijke garantie voor een systeem dat opnieuw probeert. Handlers moeten idempotent zijn.
Exponentiële backoff
Opnieuw geprobeerd over een ruim venster, zodat een korte storing u niets kost.
Versie op elke payload
Negeer een levering die een versie beschrijft die u al voorbij bent.
Zichtbaar foutlogboek
Mislukte leveringen worden opgesomd en zijn opnieuw af te spelen in plaats van stilzwijgend te verdwijnen.
Gerichte abonnementen
Abonneer per gebeurtenistype, zodat een endpoint alleen ontvangt waar het iets mee doet.
Antwoorden
Veelgestelde vragen
Hoe weet ik dat een webhook echt van CirculeID kwam?
Elke levering draagt een handtekening over de ruwe request-body en een tijdstempel. Verifieer de handtekening tegen het geheim van uw endpoint vóór het parsen, en wijs leveringen af waarvan het tijdstempel buiten uw tolerantievenster valt. Een endpoint dat een ongeverifieerde payload vertrouwt, is een endpoint waar iedereen naartoe kan posten.
Worden leveringen geordend?
Per object, naar beste vermogen — maar vertrouw er niet op. Retries en netwerkomstandigheden maken dat een oudere gebeurtenis na een nieuwere kan aankomen. Elke payload draagt de objectversie die zij weerspiegelt, dus een handler zou een levering die een reeds gepasseerde versie beschrijft moeten negeren in plaats van volgorde aan te nemen.
Wat gebeurt er als mijn endpoint uit de lucht is?
Levering wordt opnieuw geprobeerd met exponentiële backoff over een ruim venster, en het foutlogboek is zichtbaar in uw account in plaats van stil. Na afloop van het venster wordt de levering als mislukt gemarkeerd; de onderliggende wijziging blijft opvraagbaar via de API, zodat een webhookstoring vertraging veroorzaakt en geen dataverlies.
Kan dezelfde gebeurtenis twee keer worden afgeleverd?
Ja, en u moet daarvan uitgaan. At-least-once-aflevering is de eerlijke garantie voor elk systeem dat opnieuw probeert. Elke aflevering draagt een stabiele identificator, dus de juiste handler legt die identificator vast en behandelt een herhaling als een no-op — wat ook het opnieuw afspelen van een mislukt venster veilig maakt.
Mogen webhookpayloads als het volledige record worden vertrouwd?
Behandel de payload als een melding en niet als de bron van waarheid. Zij vertelt u dat er iets is veranderd en geeft u genoeg om te bepalen of het u raakt; als u erop handelt, lees dan de huidige stand terug via de API. Zo kan een verouderde of omgewisselde aflevering geen oude data in uw systeem schrijven.
Next step
Richt de eerste op een testendpoint
Abonneer in sandbox, maak uw endpoint met opzet stuk, en bekijk het retry- en replaygedrag voordat u erop vertrouwt.