Webhooks
Interessant wird es, wenn die Zustellung fehlschlägt
Signatur, Wiederholungen, Reihenfolge und Idempotenz sind der ganze Vertrag. Eine Integration, die nur den Gutfall behandelt, ist nicht fertig — sie hat nicht angefangen.
- Zustellung
- Mindestens einmal
- Signiert
- Über den Rohkörper
- Wiederholungen
- Exponentielles Backoff
Definition
Wie funktionieren Pass-Webhooks?
CirculeID sendet einen signierten Callback an Ihren Endpunkt, wenn sich ein Pass, ein Ereignis oder ein Nachweis ändert. Die Zustellung erfolgt mindestens einmal mit exponentiellem Backoff; Handler müssen daher die Signatur prüfen, wiederholte Zustellkennungen als No-op behandeln und den aktuellen Zustand vor dem Handeln über die API zurücklesen.
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.
Ereignisse
Was Sie abonnieren können
| 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 |
Verifizierung
Verifizieren, bevor Sie parsen
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);
}Vertrag
Was die Plattform garantiert
Signierte Nutzlasten
HMAC über den Rohkörper mit einem Geheimnis je Endpunkt, plus Zeitstempel.
Zustellung mindestens einmal
Die ehrliche Zusage für ein wiederholendes System. Handler müssen idempotent sein.
Exponentielles Backoff
Über ein längeres Fenster wiederholt, sodass ein kurzer Ausfall Sie nichts kostet.
Version in jeder Nutzlast
Ignorieren Sie eine Zustellung, die eine bereits überholte Version beschreibt.
Sichtbares Fehlerprotokoll
Fehlgeschlagene Zustellungen werden aufgelistet und lassen sich erneut abspielen, statt stillschweigend verloren zu gehen.
Abonnements mit Geltungsbereich
Abonnieren Sie je Ereignistyp, damit ein Endpunkt nur empfängt, worauf er reagiert.
Antworten
Häufig gestellte Fragen
Woher weiß ich, dass ein Webhook wirklich von CirculeID kam?
Jede Zustellung trägt eine Signatur über den rohen Anfragekörper und einen Zeitstempel. Prüfen Sie die Signatur gegen das Geheimnis Ihres Endpunkts, bevor Sie parsen, und weisen Sie Zustellungen zurück, deren Zeitstempel außerhalb Ihres Toleranzfensters liegt. Ein Endpunkt, der einer ungeprüften Nutzlast vertraut, ist ein Endpunkt, an den jeder senden kann.
Sind Zustellungen geordnet?
Je Objekt, nach bestem Bemühen — verlassen Sie sich aber nicht darauf. Wiederholungen und Netzbedingungen führen dazu, dass ein älteres Ereignis nach einem neueren eintreffen kann. Jede Nutzlast trägt die Objektversion, die sie abbildet; ein Handler sollte daher eine Zustellung ignorieren, die eine bereits überholte Version beschreibt, statt Reihenfolge anzunehmen.
Was passiert, wenn mein Endpunkt ausfällt?
Die Zustellung wird mit exponentiellem Backoff über ein längeres Fenster wiederholt, und das Fehlerprotokoll ist in Ihrem Konto sichtbar statt stumm. Nach Ablauf des Fensters gilt die Zustellung als fehlgeschlagen; die zugrunde liegende Änderung bleibt über die API abfragbar, sodass ein Webhook-Ausfall eine Verzögerung verursacht und keinen Datenverlust.
Kann dasselbe Ereignis zweimal zugestellt werden?
Ja, und Sie sollten davon ausgehen. At-least-once-Zustellung ist die ehrliche Garantie für jedes System, das erneut versucht. Jede Zustellung trägt eine stabile Kennung, der richtige Handler merkt sich diese Kennung und behandelt eine Wiederholung als No-op — womit auch das erneute Abspielen eines fehlgeschlagenen Zeitfensters sicher wird.
Sollte man Webhook-Nutzlasten als vollständigen Datensatz betrachten?
Behandeln Sie die Nutzlast als Benachrichtigung, nicht als Quelle der Wahrheit. Sie sagt Ihnen, dass sich etwas geändert hat, und gibt Ihnen genug, um zu entscheiden, ob es Sie betrifft; wenn Sie handeln, lesen Sie den aktuellen Zustand über die API zurück. So kann eine veraltete oder vertauschte Zustellung keine alten Daten in Ihr System schreiben.
Next step
Richten Sie den ersten auf einen Testendpunkt
Abonnieren Sie in der Sandbox, machen Sie Ihren Endpunkt absichtlich kaputt und beobachten Sie das Wiederholungs- und Wiedergabeverhalten, bevor Sie sich darauf verlassen.