Register an HTTPS endpoint to receive event notifications. Anton POSTs signed JSON deliveries to the URL for every event in events that fires on your account.
The URL must use https:// (enforced outside development) and be publicly reachable. Private, loopback and metadata addresses are refused. The response carries the signing secret, shown once. Store it now, because Anton cannot show it again. Rotate it any time with POST /v1/webhooks/{id}/secret/rotate. Requires an Idempotency-Key. Because the secret is returned once, a replay with the same key returns the same subscription with secret set to null.
See Webhook Events for the event catalog and Webhook Signing for verification.
Delivery. Each delivery is a POST with a JSON body and these headers:
| Header | Value |
|---|---|
X-Webhook-ID | The event's id. The same on every retry of one event; use it to drop duplicates. |
X-Webhook-Event | The event type, such as payout.completed. |
X-Webhook-Timestamp | When this attempt was signed, in Unix seconds. |
X-Webhook-Signature | One or more comma-separated v1=<hex> entries. |
User-Agent | AntonPayments-Webhook/1.0. The version may change; don't match it exactly. |
Each v1= entry is the lowercase hex HMAC-SHA256 of {X-Webhook-Timestamp}.{raw request body}, keyed with the endpoint's signing secret. The current secret's signature comes first. During a rotation's grace window, the previous secret's signature follows it. Accept the delivery if any entry matches the one you compute.
Your endpoint has 30 seconds to answer. Only a 2xx counts as delivered. Redirects are not followed, so a 3xx is a failed attempt, as are any other status, a timeout and a connection error. Anton retries a failed attempt with backoff.
Headers
Anton-VersionstringThe API version for this request, a date such as 2026-12-01. Optional. Without it, the request runs on your account's pinned version: the latest version when you created your first OAuth client, or the launch version (2026-12-01) if you have not created one. An unknown value returns 400 invalid_api_version. The header applies to one request and never changes your pinned version; move the pin from the dashboard. It does not apply to webhooks, which follow your pinned version. The response echoes the version used in the Anton-Version header.
"2026-12-01"Idempotency-Keystring · requiredUnique key identifying this operation. Sending the same key twice returns the original response instead of creating a duplicate. Keys are retained for 24 hours.
Body application/json
urlstring (uri) · requiredHTTPS endpoint that receives deliveries. Must be publicly reachable.
eventsarray of string · requiredEvent types to deliver, at least one.
metadataobjectYour own key-value pairs. Never put personal data in it.
Responses
201The subscription, with its one-time signing secret.
idstring · requiredUnique identifier.
objectstring · requiredThe type of the object.
webhook_subscriptionlivemodeboolean · requiredTrue in production, false in the sandbox.
statusstring · requiredWhether deliveries are sent.
activeinactiveurlstring (uri) · requiredThe endpoint URL.
eventsarray of string · requiredEvent types delivered.
metadataobject · requiredYour own key-value pairs. Never put personal data in it.
created_atstring (date-time) · requiredWhen the object was created.
"2026-04-15T14:30:00Z"updated_atstring (date-time) · requiredWhen the object last changed.
"2026-04-15T14:30:00Z"secretstring · requiredSigning secret (whsec_ + 64 hex). Shown once, here, so store it now.
"whsec_0a1b2c3d4e5f67890123456789abcdef0123456789abcdef0123456789abcdef"400Malformed JSON, an unknown field, a missing `events` or `Idempotency-Key`, or a URL that is not accepted (`webhook_url_required`, `webhook_u
errorobject · requiredThe error object of every /v1 error response. type, code, message, doc_url and request_id are always present.
Fields (7)
typestring · requiredThe kind of error; it follows the HTTP status. idempotency_error is used only for the two Idempotency-Key failures that are a 409 or a 422 (idempotency_in_flight, idempotency_key_reused).
authentication_errorpermission_errorinvalid_request_erroridempotency_errorrate_limit_errorapi_errorcodestring · requiredMachine-readable error code. Branch on this, not on message. Each code is documented at its doc_url.
"amount_precision_invalid"messagestring · requiredHuman-readable description for a developer. Never includes personal data or internal detail; a 5xx message is always generic.
"CAD amounts allow 2 decimal places; got 3."doc_urlstring (uri) · requiredWhere this code is documented.
"https://docs.antonpayments.com/api-reference/errors#amount_precision_invalid"request_idstring · requiredThe req_ ID of the request that failed; the same value as the Request-Id header.
"req_01JD3XB7Q2"paramstringThe request field or query parameter at fault, when one is. With several failures, see details.
"amount"detailsarray of objectEvery field failure at once, so a form can be fixed in one pass.
Item fields (3)
paramstring · requiredDotted JSON path to the offending field.
"amount"codestring · required"amount_precision_invalid"messagestring · required"CAD amounts allow 2 decimal places; got 3."401Missing, expired or invalid credentials (access token or DPoP proof). Carries `WWW-Authenticate`.
errorobject · requiredThe error object of every /v1 error response. type, code, message, doc_url and request_id are always present.
Fields (7)
typestring · requiredThe kind of error; it follows the HTTP status. idempotency_error is used only for the two Idempotency-Key failures that are a 409 or a 422 (idempotency_in_flight, idempotency_key_reused).
authentication_errorpermission_errorinvalid_request_erroridempotency_errorrate_limit_errorapi_errorcodestring · requiredMachine-readable error code. Branch on this, not on message. Each code is documented at its doc_url.
"amount_precision_invalid"messagestring · requiredHuman-readable description for a developer. Never includes personal data or internal detail; a 5xx message is always generic.
"CAD amounts allow 2 decimal places; got 3."doc_urlstring (uri) · requiredWhere this code is documented.
"https://docs.antonpayments.com/api-reference/errors#amount_precision_invalid"request_idstring · requiredThe req_ ID of the request that failed; the same value as the Request-Id header.
"req_01JD3XB7Q2"paramstringThe request field or query parameter at fault, when one is. With several failures, see details.
"amount"detailsarray of objectEvery field failure at once, so a form can be fixed in one pass.
Item fields (3)
paramstring · requiredDotted JSON path to the offending field.
"amount"codestring · required"amount_precision_invalid"messagestring · required"CAD amounts allow 2 decimal places; got 3."403Authenticated, but not permitted for this operation. A sandbox credential used against production is `key_environment_mismatch`.
errorobject · requiredThe error object of every /v1 error response. type, code, message, doc_url and request_id are always present.
Fields (7)
typestring · requiredThe kind of error; it follows the HTTP status. idempotency_error is used only for the two Idempotency-Key failures that are a 409 or a 422 (idempotency_in_flight, idempotency_key_reused).
authentication_errorpermission_errorinvalid_request_erroridempotency_errorrate_limit_errorapi_errorcodestring · requiredMachine-readable error code. Branch on this, not on message. Each code is documented at its doc_url.
"amount_precision_invalid"messagestring · requiredHuman-readable description for a developer. Never includes personal data or internal detail; a 5xx message is always generic.
"CAD amounts allow 2 decimal places; got 3."doc_urlstring (uri) · requiredWhere this code is documented.
"https://docs.antonpayments.com/api-reference/errors#amount_precision_invalid"request_idstring · requiredThe req_ ID of the request that failed; the same value as the Request-Id header.
"req_01JD3XB7Q2"paramstringThe request field or query parameter at fault, when one is. With several failures, see details.
"amount"detailsarray of objectEvery field failure at once, so a form can be fixed in one pass.
Item fields (3)
paramstring · requiredDotted JSON path to the offending field.
"amount"codestring · required"amount_precision_invalid"messagestring · required"CAD amounts allow 2 decimal places; got 3."422An event type is unknown (a retired name points to its replacement), or metadata is over its limits.
errorobject · requiredThe error object of every /v1 error response. type, code, message, doc_url and request_id are always present.
Fields (7)
typestring · requiredThe kind of error; it follows the HTTP status. idempotency_error is used only for the two Idempotency-Key failures that are a 409 or a 422 (idempotency_in_flight, idempotency_key_reused).
authentication_errorpermission_errorinvalid_request_erroridempotency_errorrate_limit_errorapi_errorcodestring · requiredMachine-readable error code. Branch on this, not on message. Each code is documented at its doc_url.
"amount_precision_invalid"messagestring · requiredHuman-readable description for a developer. Never includes personal data or internal detail; a 5xx message is always generic.
"CAD amounts allow 2 decimal places; got 3."doc_urlstring (uri) · requiredWhere this code is documented.
"https://docs.antonpayments.com/api-reference/errors#amount_precision_invalid"request_idstring · requiredThe req_ ID of the request that failed; the same value as the Request-Id header.
"req_01JD3XB7Q2"paramstringThe request field or query parameter at fault, when one is. With several failures, see details.
"amount"detailsarray of objectEvery field failure at once, so a form can be fixed in one pass.
Item fields (3)
paramstring · requiredDotted JSON path to the offending field.
"amount"codestring · required"amount_precision_invalid"messagestring · required"CAD amounts allow 2 decimal places; got 3."429Rate limit exceeded. See `Retry-After`. The `X-RateLimit-*` headers are on every authenticated API response, not only on 429s; they are docu
errorobject · requiredThe error object of every /v1 error response. type, code, message, doc_url and request_id are always present.
Fields (7)
typestring · requiredThe kind of error; it follows the HTTP status. idempotency_error is used only for the two Idempotency-Key failures that are a 409 or a 422 (idempotency_in_flight, idempotency_key_reused).
authentication_errorpermission_errorinvalid_request_erroridempotency_errorrate_limit_errorapi_errorcodestring · requiredMachine-readable error code. Branch on this, not on message. Each code is documented at its doc_url.
"amount_precision_invalid"messagestring · requiredHuman-readable description for a developer. Never includes personal data or internal detail; a 5xx message is always generic.
"CAD amounts allow 2 decimal places; got 3."doc_urlstring (uri) · requiredWhere this code is documented.
"https://docs.antonpayments.com/api-reference/errors#amount_precision_invalid"request_idstring · requiredThe req_ ID of the request that failed; the same value as the Request-Id header.
"req_01JD3XB7Q2"paramstringThe request field or query parameter at fault, when one is. With several failures, see details.
"amount"detailsarray of objectEvery field failure at once, so a form can be fixed in one pass.
Item fields (3)
paramstring · requiredDotted JSON path to the offending field.
"amount"codestring · required"amount_precision_invalid"messagestring · required"CAD amounts allow 2 decimal places; got 3."500Something went wrong on our end (`api_error`: 500 `internal_error`, 502 `upstream_error`, 503 `service_unavailable`). The message is always
errorobject · requiredThe error object of every /v1 error response. type, code, message, doc_url and request_id are always present.
Fields (7)
typestring · requiredThe kind of error; it follows the HTTP status. idempotency_error is used only for the two Idempotency-Key failures that are a 409 or a 422 (idempotency_in_flight, idempotency_key_reused).
authentication_errorpermission_errorinvalid_request_erroridempotency_errorrate_limit_errorapi_errorcodestring · requiredMachine-readable error code. Branch on this, not on message. Each code is documented at its doc_url.
"amount_precision_invalid"messagestring · requiredHuman-readable description for a developer. Never includes personal data or internal detail; a 5xx message is always generic.
"CAD amounts allow 2 decimal places; got 3."doc_urlstring (uri) · requiredWhere this code is documented.
"https://docs.antonpayments.com/api-reference/errors#amount_precision_invalid"request_idstring · requiredThe req_ ID of the request that failed; the same value as the Request-Id header.
"req_01JD3XB7Q2"paramstringThe request field or query parameter at fault, when one is. With several failures, see details.
"amount"detailsarray of objectEvery field failure at once, so a form can be fixed in one pass.
Item fields (3)
paramstring · requiredDotted JSON path to the offending field.
"amount"codestring · required"amount_precision_invalid"messagestring · required"CAD amounts allow 2 decimal places; got 3."