Webhook-Signaturverifizierung und Idempotenz

Webhooks benachrichtigen ein Partner-Backend über asynchrone Änderungen des Geschäftszustands. Da die Zustellung erneut versucht werden kann, muss jeder Empfänger die Signatur vor der Analyse vertrauenswürdiger Daten überprüfen und das Ereignis idempotent verarbeiten.

Webhook-Header

Header	Beschreibung
X-Agent-Zeitstempel	Unix-Zeitstempel in Sekunden.
X-Agent-Nonce	Wiederholungsschutz-Nonce.
X-Agent-Signatur	HMAC–SHA256 Unterschrift.

timestamp + nonce + rawBody

Verwenden Sie beim Rekonstruieren des signierten Werts genau den rohen Request-Body, der über HTTP erhalten wurde. Das Parsen und Neuserialisieren JSON zuerst kann den Leerraum oder die Feldreihenfolge verändern und eine andere Signatur erzeugen.

Verifikationsfluss

Lesen Sie die Zeitstempel-, Nonce- und Signatur-Header.
Erfassen Sie den unveränderten rohen Request-Körper.
Baue timestamp + nonce + rawBody.
Berechnen Sie HMAC–SHA256 mit dem Partner API Geheimnis.
Vergleichen Sie die berechneten und empfangenen Signaturen mit einem konstanten Zeitvergleich.
Wenden Sie die genehmigten Zeitstempel-Frische- und Nonce-Wiederverwendungsprüfungen an.
Erst nach erfolgreicher Verifikation das Ereignis analysieren und verarbeiten.

Wenn ein offizieller Agent SDK -Verifizierer verfügbar ist, verwenden Sie ihn, anstatt einen unabhängigen Unterzeichnungscode zu führen.

Orderidopotenz

Fall	Handhabung
Erster Übertragungsantrag	Schaffen Sie ein weltweit einzigartiges agentOrderNo.
HTTP Auszeit	Fragen Sie die ursprüngliche agentOrderNo ab, bevor Sie eine neue erstellen.
PROCESSING Antwort	Warte auf den Status der Webhook- oder Abfragereihenfolge.
Wiederholter Webhook	Deduplizieren Sie nach Idempotenzschlüssel und Endstatus.

Empfohlene Idempotenzaufzeichnung

Speichern Sie genügend Informationen, um eine wiederholte Lieferung zu erkennen und sicher zurückzugewinnen:

Spielfeld	Zweck
Ereignis- oder Geschäftsschlüssel	Identifiziert eindeutig die Benachrichtigung oder Operation.
PartnerOrdersnummer	Verbindet das Ereignis mit der ursprünglichen Anfrage.
Payload-Hash	Hilft, widersprüchliche wiederholte Nutzlasten zu identifizieren.
Aktueller Verarbeitungszustand	Unterscheidet empfangene, verarbeitete, erfolgreiche und fehlgeschlagene Arbeiten.
Endgültiger Geschäftsstatus	Verhindert, dass eine terminale Aktion zweimal angewendet wird.
Bearbeitungszeitstempel	Unterstützt Richtlinien zur Untersuchung und Verwertung.

Beziehen Sie die Geschäftsänderung und die Impotenzdatensatz, wo möglich, in derselben Transaktion ein. Ein wiederholtes Ereignis sollte das bereits bekannte Ergebnis zurückgeben, anstatt die Bilanz, Reihenfolge oder Benutzeränderung erneut anzuwenden.

Auszeit- und Wiederholungsregel

Ein HTTP Timeout beweist nicht, dass die ursprüngliche Anfrage fehlgeschlagen ist. Abfrage der Operation mit dem ursprünglichen agentOrderNooder warten Sie auf den Webhook, bevor Sie entscheiden, ob eine weitere Aktion erforderlich ist. Das Erstellen einer neuen GeschäftsOrdersnummer nach jedem Timeout kann zu doppelten Kapitalbewegungen führen.

Produktionscheckliste

Verifizieren Sie die Signatur vor JSON Parsing oder Geschäftsverarbeitung.
Erhalte den rohen Körper unabhängig von der geanalysten Nutzlast.
Veraltete oder wiederholte Anfragen gemäß der genehmigten Integrationsrichtlinie ablehnen.
Ereignisverarbeitung für wiederholte und nicht in der Reihenfolge zugeteilte Zustellung sicher zu machen.
Protokolliere Ereignis-IDs, Partnerbefehlsnummern, Verarbeitungsergebnis und Anforderungszeit.
Geheimnisse und Signaturwerte aus Protokollen und Support-Anhängen zu schwärzen.

Geheimnisse & HMAC Signieren

Schützen Sie das API Geheimnis, das für Anfragen und Webhook-Verifizierung verwendet wird.

Agent SDK Überblick

Überprüfen Sie den vollständigen Backend-Integrationsworkflow.

SDK Fehlerbehebung