Zum Hauptinhalt springen
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.
Create webhook endpoint
Speichern Sie das Antwort-data.id als WEBHOOK_ID. Fordern Sie mit einem API-Schlüssel, der webhooks:write hat, eine Portal-URL von GET /v3/webhooks/portal an, rufen Sie das Signaturgeheimnis dieses Endpunkts ab und speichern Sie es separat von Ihrem API-Schlüssel in einem Secret-Manager. Die Portal-URL gewährt für sich allein Zugriff und läuft nach einer Stunde ab. Fordern Sie daher jedes Mal eine neue an und speichern oder teilen Sie sie nicht. Das Portal gruppiert v3-Ereignisse nach Ressource: Customers, Capabilities, Accounts, Recipients, Transfers und API. Zu jedem Ereignis werden das Payload-Schema und ein Beispiel angezeigt. Legacy-Ereignisse werden als veraltet gekennzeichnet und in einer separaten Legacy-Gruppe aufgeführt. Wenn Ihr Endpunkt bereits ein Legacy-Ereignis abonniert, erhält er es weiterhin. Wählen Sie für neue Abonnements v3-Ereignisnamen.

Ereignisse eines Endpunkts ändern

Lesen Sie einen einzelnen Endpunkt mit GET /v3/webhooks/{webhookId}. Die Antwort hat dieselbe events-Struktur wie GET /v3/webhooks. Sie enthält niemals das Signaturgeheimnis. Lesezugriffe erfordern webhooks:read und geben für eine unbekannte Endpunkt-ID 404 not_found zurück. Aktualisieren Sie den Endpunkt mit PATCH /v3/webhooks/{webhookId}. Senden Sie einen Idempotency-Key-Header. Aktualisierungen erfordern webhooks:write.
  • Senden Sie nur events, um die aktuelle URL beizubehalten.
  • Senden Sie nur url, um die aktuelle Ereignisauswahl beizubehalten.
  • events ersetzt die gesamte Auswahl. Lesen Sie zuerst den Endpunkt und geben Sie jedes Ereignis an, das Sie weiterhin benötigen.
  • Neue Abonnements müssen v3-Ereignisnamen verwenden.
  • Sie können einen Legacy-Ereignisnamen beibehalten, wenn der Endpunkt ihn bereits abonniert. Das Hinzufügen eines neuen Legacy-Namens gibt 400 validation_error zurück.
Dieser Body behält die URL bei und ersetzt die Auswahl:
Request body

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.
Verify signature
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:
Refetch transfer
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. Mit webhooks:write können Sie außerdem fehlgeschlagene Zustellungen wiederholen oder einen manuellen Replay starten. Ein Schlüssel mit nur webhooks:read öffnet ein Portal, das Zustellungen anzeigt, sie aber weder wiederholen noch erneut abspielen und auch keine Signaturgeheimnisse offenlegen kann. 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.