Webhooks

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.

Frequently Asked Questions

• What happens if my endpoint is down longer than the retry window? After retries are exhausted, the event is not redelivered automatically — reconcile the gap by polling GET /v1/payouts, which always reflects the authoritative state of every payout.
• Why might I receive the same event twice? Delivery is at-least-once by design: a retry can fire after a slow-but-successful delivery. Deduplicate on event_id and treat handlers as idempotent.
• Can I test webhooks without real payments? Yes — the sandbox emits the full event sequence for simulated payouts, including failure and return scenarios.
• How do I rotate a webhook secret safely? Rotate from the developer portal — both old and new secrets are honoured for 24 hours, so you can deploy the new secret to your servers without a verification gap.