Overview
Webhooks let you react to events in real time instead of polling the API. This guide covers setting up a subscription, verifying signatures, building a receiver endpoint, and handling events reliably.Available events
| Event | Description |
|---|---|
payout.created | A new payout has been created |
payout.screening | Compliance screening has started |
payout.processing | Payout approved and submitted to rail |
payout.sent | Rail confirmed dispatch |
payout.completed | Funds delivered to payee |
payout.failed | Payout could not be completed |
payout.returned | Funds returned after delivery attempt |
payout.cancelled | Payout was cancelled |
payee.created | A new payee was created |
payee.updated | Payee details were modified |
payee.deleted | A payee was deleted |
batch.completed | All payouts in a batch have resolved |
batch.failed | Batch processing encountered errors |
1. Create a webhook subscription
Register your endpoint URL and choose which events to listen for:Response
2. Verify webhook signatures
Every webhook delivery includes an HMAC-SHA256 signature in theAnton-Signature header. Always verify this signature before processing the event to confirm it originated from Anton.
The signature header contains a timestamp and signature:
Verification logic
- Extract the timestamp (
t) and signature (v1) from the header - Construct the signed payload:
{timestamp}.{raw_request_body} - Compute HMAC-SHA256 using your signing secret
- Compare the computed signature with the received signature
- Reject if the timestamp is more than 5 minutes old (replay protection)
3. Build your endpoint
Your webhook endpoint must:- Accept
POSTrequests with aContent-Type: application/jsonbody - Verify the
Anton-Signatureheader on every request - Return a
2xxstatus code within 30 seconds - Be publicly accessible over HTTPS
4. Handle failures gracefully
Return 200 immediately
Acknowledge receipt quickly. If processing takes time, queue it for async handling. Anton times out after 30 seconds and will retry.
Make it idempotent
You may receive the same event more than once (retries). Use the
event.id to deduplicate — store processed event IDs and skip duplicates.Retry and delivery behavior
Anton retries failed webhook deliveries with exponential backoff:| Attempt | Delay |
|---|---|
| 1 | Immediate |
| 2 | 1 minute |
| 3 | 5 minutes |
| 4 | 30 minutes |
| 5 | 2 hours |
| 6 | 8 hours |
- Your endpoint returns a non-2xx status code
- The request times out after 30 seconds
- A connection cannot be established
5. Monitor deliveries
Check the delivery history for a webhook event:Testing locally
For local development, use a tunnel service to expose your local endpoint:Best practices
Respond fast
Return
200 within 5 seconds. Queue heavy processing for later.Verify signatures
Always validate the
Anton-Signature header. Reject requests with invalid or missing signatures.Deduplicate
Track event IDs to prevent processing the same event twice.
Log everything
Log the full event payload for debugging and audit.
Set up alerts
Monitor for delivery failures — if your endpoint goes down, events queue up.
Use HTTPS
Your webhook endpoint must use HTTPS with a valid TLS certificate.