Skip to main content
Verwenden Sie Webhooks, um auf asynchrone Änderungen zu reagieren. Die Zustellung erfolgt mindestens einmal, daher sind doppelte, verzögerte und außer der Reihenfolge eintreffende Ereignisse normal.

Registrieren Sie nur die Ereignisse, die Sie benötigen

Legen Sie einen Endpunkt mit POST /v3/webhooks an. Abonnieren Sie nur dokumentierte Ereignisse, die Ihre Integration steuern. Dieses Beispiel verwendet transfer.state_changed.
Speichern Sie das Antwort-data.id als WEBHOOK_ID. Öffnen Sie das Portal, das von GET /v3/webhooks/portal zurückgegeben wird, rufen Sie das Signaturgeheimnis dieses Endpunkts ab und speichern Sie es separat von Ihrem API-Schlüssel in einem Secret-Manager.

Verifizieren vor dem Parsen

Swipelux liefert neue Webhook-Integrationen über Svix aus. Verifizieren Sie den rohen Request-Body mit Ihrem Endpunkt-Signaturgeheimnis und diesen Headern:
  • svix-id
  • svix-timestamp
  • svix-signature
Parsen Sie kein JSON und lösen Sie keine Seiteneffekte aus, bevor die Verifizierung erfolgreich ist.
Weisen Sie Anfragen mit fehlenden oder ungültigen Signaturen zurück. Halten Sie den rohen Body verfügbar, bis die Verifizierung abgeschlossen ist.

Persistieren, bestätigen, dann verarbeiten

Setzen Sie eine Eindeutigkeitsbeschränkung auf die Envelope-id. Persistieren Sie den verifizierten Envelope, geben Sie zeitnah 2xx zurück und verarbeiten Sie ihn anschließend asynchron. Wenn die Ereignis-ID bereits existiert, bestätigen Sie die Zustellung, ohne abgeschlossene Seiteneffekte zu wiederholen. Setzen Sie anstehende oder fehlgeschlagene lokale Arbeit über Ihre eigene Retry-Warteschlange fort. Verwenden Sie das Envelope-Feld attempt weder als Deduplizierungsschlüssel noch als Transport-Retry-Zähler.

Aktuellen Zustand erneut abrufen

Die Webhook-Reihenfolge ist keine maßgebliche Ressourcenhistorie. Verwenden Sie resource.type und resource.id, um das Objekt zu lokalisieren, und rufen Sie dann seinen aktuellen Zustand ab, bevor Sie Ihr System aktualisieren. Für ein Transfer-Ereignis rufen Sie GET /v3/transfers/{transferId} auf:
Steuern Sie kundensichtbaren Status und nachgelagerte Aktionen anhand der aktuellen API-Antwort. Gestalten Sie Seiteneffekte so, dass sie sicher bleiben, wenn zwei Worker zusammenhängende Ereignisse in einer anderen Reihenfolge verarbeiten.

Zustellungen wiederherstellen

Verwenden Sie GET /v3/webhooks/portal, um Zustellungsprotokolle zu öffnen, fehlgeschlagene Zustellungen zu wiederholen oder einen manuellen Replay zu starten. Jeder Replay muss dieselbe Signaturverifizierung und dieselbe dauerhafte Inbox durchlaufen. Um nach einem Ausfall wiederherzustellen, spielen Sie das betroffene Fenster erneut ab und rufen Sie jede referenzierte Ressource erneut ab. Abgeschlossene Ereignis-IDs bleiben No-Ops; unvollständige Datensätze werden asynchron fortgesetzt. Verifizieren Sie als Nächstes doppelte und außer der Reihenfolge eintreffende Zustellungen in der Sandbox und schließen Sie dann die Go-Live-Checkliste ab.