Naar hoofdinhoud gaan
Gebruik webhooks om te reageren op asynchrone wijzigingen. Bezorging is at-least-once, dus dubbele, vertraagde en out-of-order events zijn normaal.

Registreer alleen de events die je nodig hebt

Maak een endpoint aan met POST /v3/webhooks. Abonneer alleen op gedocumenteerde events die je integratie aansturen. Dit voorbeeld gebruikt transfer.state_changed.
Create webhook endpoint
Bewaar de respons 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 met GET /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 events om de huidige URL te behouden.
  • Verstuur alleen url om de huidige eventselectie te behouden.
  • events vervangt 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.
Deze body behoudt de URL en vervangt de selectie:
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-id
  • svix-timestamp
  • svix-signature
Parseer geen JSON en veroorzaak geen side effects voordat de verificatie is geslaagd.
Verify signature
Weiger requests met ontbrekende of ongeldige signatures. Houd de raw body beschikbaar totdat de verificatie is voltooid.

Persisteer, bevestig, verwerk

Zet een uniqueness constraint op de envelope id. 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. Gebruik resource.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
Baseer de klantstatus en downstream-acties op de huidige API-respons. Ontwerp side effects zodat ze veilig blijven als twee workers gerelateerde events in verschillende volgorde verwerken.

Herstel deliveries

Gebruik GET /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.