Webhooks
Receive signed, real-time notifications for every payout lifecycle event — so your system never has to poll.
Event Catalogue
payout.created— A payout was accepted and queued for processing.payout.processing— Funds are moving on the selected rail.payout.settled— Beneficiary credited. Includes final FX rate and settlement reference.payout.failed— Payout could not complete. Includes machine-readable failure reason.payout.returned— Funds returned by the receiving institution.quote.locked— An FX quote was locked for execution.beneficiary.verified— Beneficiary account verification completed.kyb.status_changed— Your business verification status changed.
Signatures
Every delivery includes an X-KeyBS-Signature header — an HMAC-SHA256 of the raw request body using your webhook secret. Verify the signature and reject any payload that does not match before processing. Secrets are rotatable from the developer portal without downtime (both old and new secrets are honoured for 24 hours).
Delivery & Retries
Deliveries expect a 2xx response within 10 seconds. Failed deliveries are retried with exponential backoff for up to 24 hours (8 attempts). Events carry a unique event_id — treat processing as idempotent, as the same event may occasionally be delivered more than once.
Best Practices
Respond 200 immediately and process asynchronously · verify signatures on every request · use the event_id for deduplication · reconcile daily against GET /v1/payouts as the source of truth.