A payout does not finish when POST /v1/payouts returns. Each status change is sent to a URL you control as a signed HTTPS request, carrying the same payout object GET /v1/payouts/{id} would return. Polling shows you the same change later and spends rate limit doing it.
Choose the events
A subscription lists the event types it wants, and PATCH /v1/webhooks/{id} changes the list later, so start with less.
Each type is named in full. There is no payout.* pattern. The only wildcard is *, which delivers every event type on your account, including ones added later, so a handler that uses it must ignore types it does not know. An unknown name is refused with 422, and a retired name points at its replacement. payout.on_hold replaced payout.screening_failed.
Create the subscription
The response carries the subscription id (whk_...) and the signing secret (whsec_...). Store the secret now. It is never shown again.
curl -X POST \ https://api.antonpayments.dev/v1/webhooks \ -H "Authorization: DPoP $ANTON_ACCESS_TOKEN" \ -H "DPoP: $DPOP_PROOF" \ -H "Idempotency-Key: webhook-orders-1" \ -H "Content-Type: application/json" \ -d '{ "url": "https://example.com/hooks", "events": [ "payout.completed", "payout.failed", "payout.returned", "payout.on_hold" ], "metadata": { "team": "payments" } }'
The url must be HTTPS and publicly reachable. Loopback, private and metadata addresses are refused. A retry with the same Idempotency-Key returns the same subscription with secret set to null, so a lost secret is not recovered that way. Rotate it instead.
Before a real payout depends on the receiver, send it a test event with POST /v1/webhooks/{id}/test.
What arrives
Every delivery is the same envelope. The payout is in data.object, and the event id (evt_...) is the same on every retry. A retry sends the same bytes as the first attempt: the event is rendered once, at the API version your account was pinned to.
| Header | Use |
|---|---|
X-Webhook-ID | The event id. Deduplicate on it. |
X-Webhook-Event | The event type. |
User-Agent | AntonPayments-Webhook/1.0. The version can change, so don't match it exactly. |
X-Webhook-Timestamp | Unix seconds when the delivery was signed. |
X-Webhook-Signature | One or more v1= HMAC-SHA256 signatures. |
Verify the signature before you read the body as truth. Verify webhook signatures has the handler in four languages.
A payout must never complete in your system on an unverified request. Anyone who finds the URL can post to it.
Make the handler safe to repeat
- Delivery is at least once. Keep the event ids you have applied and skip a repeat.
- Order is not guaranteed. Events for one payout are dispatched in order, but retries can reorder them at your endpoint. Compare
created_atwith the last event you applied for that payout. - Set your record from
status. Events can arrive late or twice. Readdata.object.status, so applying an event twice leaves the same state. - Final statuses stay final.
completed,returned,cancelledandfailedend a payout. Never move one out of them because a late event arrived.
Treat a status you do not know as still in progress, and a failure_code you do not know as a plain failure. New values then never break the handler.
A hold is not an error. payout.on_hold is a review and carries no reason: the payout's status_message is the only text Anton gives. Show your user a pending state, not an error. It resumes as processing or ends as cancelled or failed. A payout Anton could not process arrives as payout.failed with failure_code set to cannot_be_processed, and the response gives no more. Contact support with the request_id and the payout id.
Answer fast, retry safely
Answer with a 2xx within 30 seconds, and do the work from a queue. Any other response counts as a failed delivery, and Anton does not follow a 3xx. Failed deliveries are retried with exponential backoff, five attempts in all, then abandoned. No endpoint replays an abandoned delivery, so keep a way to reconcile. GET /v1/webhooks/events lists every event for your account, and Run webhooks in production covers reading the attempts and closing a gap.
When it goes wrong
url must use https://. Put the receiver behind TLS.url is loopback, private, internal or a metadata address. Use a public HTTPS endpoint.events is not a known event type. details[].param names it, for example events[0]. Check the name against GET /v1/webhooks/event-types.Retry-After, then retry with the same Idempotency-Key.If every delivery fails your own check, you are hashing a parsed body instead of the raw bytes, or holding a secret that has since been rotated.