Webhook Signaturüberprüfung und Idempotenz

Diese Seite folgt Agent Java SDK WEBHOOKS.md beim Commit fa6c7b6. Dies ist ein reines Dokumentationsupdate. Es wurde kein neues SDK-Artefakt veröffentlicht, das Warnhilfsmethoden enthält.

Alle vier Ereignistypen verwenden einen Händler-Callback URL und werden vom Body event versendet. Sehen Webhook Ereignisse und Liquidationswarnungen für Ereignisfelder und Payload-Beispiele.

Webhook-Header

timestamp + nonce + rawBody

Ereignis-Idempotenz

Behalten Sie die Deduplizierung innerhalb des Händler- und environment-Bereichs bei, atomar mit der Geschäftsverarbeitung. Verschiedene notificationId-Werte identifizieren unabhängige FIRST/UPGRADE/REMINDER-Benachrichtigungen; Verwerfen Sie Benachrichtigungen nicht durch Gruppierung nach Benutzer, Episode oder eventType. Ein leerer Idempotenzschlüssel kann nicht für die Deduplizierung verwendet werden. Der SDK gibt nur einen Hilfsschlüssel zurück; Es werden keine Geschäftsdaten gespeichert oder verarbeitet. Erfassen Sie dieselbe Identität mit einer anderen Stelle als Konflikt. Überschreiben Sie nicht den verarbeiteten Körper.

Überprüfung und Empfang der Unterschrift

Verwenden Sie das Händlergeheimnis API, um die HMAC-SHA256 Hexadezimalsignatur von timestamp + nonce + rawBody zu berechnen. Überprüfen Sie die ursprünglich empfangenen Bytes. Formatieren Sie JSON nicht, benennen Sie Felder nicht um und serialisieren Sie den Text nicht zuerst neu.

Überprüfen Sie zuerst die Signatur und dann das Zeitfenster (empfohlen ±300 Sekunden), den Händler und die Umgebung. Extrahieren Sie als Nächstes die Idempotenzidentität und verarbeiten Sie die Benachrichtigung zuverlässig. Unbekannte Ereigniswerte für die Diagnose aufbewahren; Interpretieren Sie sie niemals als Erfolg des Fonds. Der Überprüfungshelfer führt keine Zeitfenster-, Besitz- oder dauerhaften Deduplizierungsprüfungen durch.

Geben Sie HTTP 2xx zurück, nachdem die Verarbeitung abgeschlossen oder ein identisches Duplikat bestätigt wurde. Bei Fehler Nicht-2xx zurückgeben. Der Absender der Warnung hat eine Zeitüberschreitung von 5 Sekunden HTTP und maximal 8 Versuche. Bei Wiederholungsversuchen bleibt der eingefrorene Körper erhalten; Nur der Signaturzeitstempel und die Nonce ändern sich. Reagieren Sie zeitnah nach zuverlässiger Annahme; Langfristige Geschäftsarbeiten können die eigenen persistenten Aufgaben des Händlers nutzen.

Händlerbenachrichtigungen hängen nicht vom Online-Status des Benutzers ab. Plattformbenutzer-Pushs erfolgen ausschließlich online und nach bestem Wissen und Gewissen, ohne Offline-Wiedergabe. Phase eins hat keinen Benachrichtigungseingang.

Erfolgreiche Antworten und Stoppen von Wiederholungsversuchen

Fondsrückrufe und Liquidationswarnungen verwenden nur den HTTP-Statuscode, um den Liefererfolg zu bestimmen. Der Absender interpretiert den Antworttext code, success, result oder message nicht und erfordert keine feste Antwort OK / success.

Der Antworttext kann leer, Text oder JSON sein. Die Beispielfelder result dienen der Information des Händlers und sind keine Protokollanforderungen. 202 Accepted stoppt auch Plattform-Wiederholungsversuche. Geben Sie es daher erst zurück, nachdem die Benachrichtigung zuverlässig in der permanenten Aufgabenwarteschlange des Händlers gespeichert wurde, und nicht nur nach dem Starten einer asynchronen Aufgabe im Arbeitsspeicher.

Beispiele für erfolgreiche Antworten

Nachdem die Geschäftsverarbeitung abgeschlossen ist oder die Benachrichtigung zuverlässig in der eigenen Warteschleife des Händlers gespeichert wurde:

HTTP/1.1 200 OK
Content-Type: application/json
{"result":"RECEIVED"}

Wenn kein Antworttext erforderlich ist:

HTTP/1.1 204 No Content

Überspringen Sie bei einer bereits verarbeiteten Benachrichtigung mit identischem Text die doppelte Geschäftsverarbeitung und geben Sie trotzdem 2xx zurück:

HTTP/1.1 200 OK
Content-Type: application/json
{"result":"DUPLICATE"}

Beispiele für Fehlerreaktionen

Wenn die Datenbank vorübergehend nicht verfügbar ist und der Händler die Verarbeitung weder abgeschlossen noch die Benachrichtigung zuverlässig gespeichert hat, geben Sie „non-2xx“ zurück, damit die Plattform es erneut versuchen kann:

HTTP/1.1 503 Service Unavailable
Content-Type: application/json
{"result":"FAILED","message":"temporary storage failure"}

Lehnen Sie eine ungültige Signatur ab, ohne Geschäftsdaten oder erfolgreiche Deduplizierungsdatensätze zu aktualisieren:

HTTP/1.1 401 Unauthorized
Content-Type: application/json
{"result":"INVALID_SIGNATURE"}

Diese Antwortkörper ändern keine Wiederholungsentscheidungen. Erwarten Sie nicht, dass ein 401 oder 409 Wiederholungsversuche dauerhaft stoppt. Untersuchen Sie die Signatur, den Benachrichtigungsinhalt oder die Händlerkonfiguration.

Falsches Beispiel: Die folgende Antwort zählt weiterhin als erfolgreiche Zustellung. Die Plattform führt aufgrund von success:false keinen erneuten Versuch durch.

HTTP/1.1 200 OK
Content-Type: application/json
{"success":false,"code":500,"message":"processing failed"}

Wenn das Framework oder der globale Ausnahmehandler Geschäftsausfälle in HTTP 200 umschließt, legen Sie explizit den richtigen Fehlerstatus am Callback-Endpunkt fest.

Zuverlässige Quittierung und Duplikatzustellung

Empfohlene Reihenfolge: Überprüfen Sie die Signatur und überprüfen Sie Zeit/Händler/Umgebung → extrahieren Sie die Idempotenzidentität → verarbeiten Sie Geschäftsdaten und erfolgreiche Deduplizierungsdatensätze in einer Transaktion oder speichern Sie eine ausstehende Aufgabe zuverlässig → geben Sie 200/204 zurück, nachdem das Commit erfolgreich war. Geben Sie vor einem erfolgreichen Datenbankschreibvorgang nicht 2xx zurück und markieren Sie die Benachrichtigung nicht als verarbeitet.

Nach erfolgreicher Händlerverarbeitung kann es immer noch zu einer doppelten Zustellung kommen: Die Antwort geht möglicherweise verloren oder die Plattform empfängt möglicherweise 2xx, bleibt aber nicht bestehen SUCCESS. HTTP Rückrufe garantieren keine einmalige Zustellung. Behalten Sie die Deduplizierung im Händler- und environment-Bereich bei. Mittelverwendung orderType:orderId:targetStatus; Warnungen verwenden liquidation.warning:notificationId. Für einen identischen bereits bearbeiteten Körper senden Sie 2xx ohne Gutschrift oder erneute Mahnung zurück. Zeichnen Sie für dieselbe Identität mit einem anderen Körper einen Konflikt auf und geben Sie Nicht-2xx zurück. Überschreiben Sie nicht den ursprünglichen Datensatz.

Eine erfolgreiche Bestätigung bedeutet, dass der Händler die Benachrichtigung erhalten/verarbeitet hat und nicht, dass der Geldvorgang erfolgreich war. Nachdem Sie eine gültige Mittelmitteilung mit targetStatus=FAILED erfasst haben, geben Sie auch 2xx zurück; Das Scheitern einer Order ist kein Grund, die Bestätigung einer Benachrichtigung abzulehnen.

Finanzierungs- und Umweltgrenzen

Die ursprünglichen Vertragsübertragungsabläufe webhook und queryOrder gelten nicht automatisch für die Finanzierung. Bestätigen Sie Finanzierungsvorgänge mit queryWalletTransfer und der ursprünglichen Orderumgebung. Finanzierungsverwendungen status; Ursprüngliche Vertragsübertragungsantworten verwenden orderStatus. Eine erfolgreiche HTTP-Antwort oder code=0 allein beweist nicht, dass Gelder bewegt wurden.

Zu den expliziten simulierten Vertragsübertragungsbenachrichtigungen gehören environment=SIMULATED. Überprüfen Sie zuerst den Rohkörper und vergleichen Sie dann den Benutzer, den Betrag, die Orderidentität und die Umgebung mit der gespeicherten lokalen GeschäftsOrder.

Leitfaden zur Finanzierungswiederherstellung · Umweltführer