Developers
Webhooks
Signed events for every state transition — with redelivery, test pings, and replay.
Subscribe to events instead of polling. Every payment state transition, screening decision, match, and return emits a signed event.
Core events
| Event | Fires when |
|---|---|
payment.cleared |
Screening passed; settlement begins |
payment.held |
Payment held for review — build your exception flow on this |
payment.declined |
Screening declined the payment |
payment.settled |
Finality reached |
expected_payment.matched |
An incoming payment matched a declaration |
return.created / return.settled |
Funds coming back |
ping.test |
Manual test event — verify your endpoint wiring anytime |
Signatures
Every delivery is signed (Onzo-Signature header, HMAC-SHA256 over the raw body with your endpoint secret). Verify the signature before trusting any event. Reject unsigned or stale (>5 min) deliveries.
Delivery guarantees
- At-least-once delivery with exponential backoff for 72 hours
- Events are retained 30 days and can be redelivered from the dashboard or API
- Design your handler to be idempotent — you may receive an event twice
Return `2xx` fast (under 5 seconds) and process asynchronously. Slow handlers cause retries, and retries cause the duplicates your idempotent handler now gracefully absorbs.