Anton.Docs
Dashboard (opens in a new tab)

Track payouts with webhooks

Delivery is at least once and arrival order is not guaranteed. Build the receiver around those two facts.

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.

Before you begin

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

POST/v1/webhooksCreate the subscription

The response carries the subscription id (whk_...) and the signing secret (whsec_...). Store the secret now. It is never shown again.

Reference
Not yet tested in sandbox
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.

HeaderUse
X-Webhook-IDThe event id. Deduplicate on it.
X-Webhook-EventThe event type.
User-AgentAntonPayments-Webhook/1.0. The version can change, so don't match it exactly.
X-Webhook-TimestampUnix seconds when the delivery was signed.
X-Webhook-SignatureOne 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_at with the last event you applied for that payout.
  • Set your record from status. Events can arrive late or twice. Read data.object.status, so applying an event twice leaves the same state.
  • Final statuses stay final. completed, returned, cancelled and failed end 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

400webhook_url_not_https
The url must use https://. Put the receiver behind TLS.
400webhook_url_private_address
The url is loopback, private, internal or a metadata address. Use a public HTTPS endpoint.
422validation_error
An entry in events is not a known event type. details[].param names it, for example events[0]. Check the name against GET /v1/webhooks/event-types.
409webhook_subscription_inactive
You sent a test delivery to a deactivated subscription. Activate it first.
429rate_limit_exceeded
Wait the seconds in 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.

Next

Something wrong or missing here? Open an issue (opens GitHub in a new tab) ↗