Registreer alleen de events die je nodig hebt
Maak een endpoint aan metPOST /v3/webhooks. Abonneer alleen op gedocumenteerde events die je integratie aansturen. Dit voorbeeld gebruikt transfer.state_changed.
Create webhook endpoint
data.id als WEBHOOK_ID. Vraag een portal-URL op via GET /v3/webhooks/portal met een API-key die webhooks:write heeft, haal het signing secret van dit endpoint op en bewaar het los van je API-key in een secret manager. De portal-URL geeft op zichzelf toegang en verloopt na één uur, dus vraag elke keer een nieuwe aan en bewaar of deel hem niet.
Het portal groepeert v3-events per resource: Customers, Capabilities, Accounts, Recipients, Transfers en API. Elk event toont zijn payload-schema en een voorbeeld. Legacy-events zijn als deprecated gemarkeerd en staan in een aparte Legacy-groep. Als je endpoint al op een legacy-event is geabonneerd, blijft het dat event ontvangen. Kies v3-eventnamen voor nieuwe abonnementen.
Wijzig de events van een endpoint
Lees één endpoint metGET /v3/webhooks/{webhookId}. De respons heeft dezelfde events-structuur als GET /v3/webhooks. Het signing secret wordt nooit meegestuurd. Reads vereisen webhooks:read en retourneren 404 not_found voor een onbekende endpoint-ID.
Werk het endpoint bij met PATCH /v3/webhooks/{webhookId}. Verstuur een Idempotency-Key-header. Updates vereisen webhooks:write.
- Verstuur alleen
eventsom de huidige URL te behouden. - Verstuur alleen
urlom de huidige eventselectie te behouden. eventsvervangt de volledige selectie. Lees het endpoint eerst en neem elk event op dat je nog nodig hebt.- Nieuwe abonnementen moeten v3-eventnamen gebruiken.
- Je kunt een legacy-eventnaam behouden als het endpoint er al op is geabonneerd. Het toevoegen van een nieuwe legacy-naam retourneert
400 validation_error.
Request body
Verifieer voordat je parseert
Swipelux levert nieuwe webhook-integraties via Svix. Verifieer de raw request body met je endpoint signing secret en deze headers:svix-idsvix-timestampsvix-signature
Verify signature
Persisteer, bevestig, verwerk
Zet een uniqueness constraint op de envelopeid. Persisteer de geverifieerde envelope, retourneer snel 2xx en verwerk het daarna asynchroon.
Als de event-ID al bestaat, bevestig je de delivery zonder voltooide side effects te herhalen. Hervat pending of gefaald lokaal werk via je eigen retry queue. Gebruik het envelope attempt-veld niet als deduplication key of transport retry counter.
Refetch huidige state
Webhook-volgorde is geen gezaghebbende resource-geschiedenis. Gebruikresource.type en resource.id om het object te vinden en haal daarna de huidige state op voordat je je systeem bijwerkt.
Voor een transfer-event roep je GET /v3/transfers/{transferId} aan:
Refetch transfer
Herstel deliveries
GebruikGET /v3/webhooks/portal om delivery logs te openen. Met webhooks:write kun je ook gefaalde deliveries opnieuw proberen of een handmatige replay starten. Een key met alleen webhooks:read opent een portal dat deliveries toont, maar ze niet opnieuw kan proberen, niet kan replayen en geen signing secrets kan tonen.
Elke replay moet dezelfde signature-verificatie en duurzame inbox doorlopen. Om te herstellen na downtime replay je het getroffen venster en refetch je elke verwijzende resource. Voltooide event-ID’s blijven no-ops; onvoltooide records worden asynchroon hervat.
Verifieer vervolgens dubbele en out-of-order deliveries in sandbox en voltooi de Go-live-checklist.