Registrieren Sie nur die Ereignisse, die Sie benötigen
Legen Sie einen Endpunkt mitPOST /v3/webhooks an. Abonnieren Sie nur dokumentierte Ereignisse, die Ihre Integration steuern. Dieses Beispiel verwendet transfer.state_changed.
Create webhook endpoint
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 mitGET /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. eventsersetzt 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_errorzurück.
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-idsvix-timestampsvix-signature
Verify signature
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 Sieresource.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
Zustellungen wiederherstellen
Verwenden SieGET /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.