Anton.Docs
Dashboard (opens in a new tab)

Update a webhook subscription

PATCH/v1/webhooks/{id}

Change the URL, the events or the metadata. Only the fields you send change. metadata replaces the whole map, and null clears it. url and events cannot be cleared. Status and secret have their own actions. Accepts an Idempotency-Key but does not require one.

Path parameters

idstring · required

Webhook subscription ID (prefixed whk_).

Headers

Anton-Versionstring

The 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.

Example: "2026-12-01"

Body application/json

urlstring (uri)

New endpoint URL.

eventsarray of string

The full new list of event types.

metadataobject | null

The full new metadata map, or null to clear it.

Responses

200The updated subscription.
idstring · required

Unique identifier.

objectstring · required

The type of the object.

webhook_subscription
livemodeboolean · required

True in production, false in the sandbox.

statusstring · required

Whether deliveries are sent.

activeinactive
urlstring (uri) · required

The endpoint URL.

eventsarray of string · required

Event types delivered.

metadataobject · required

Your own key-value pairs. Never put personal data in it.

created_atstring (date-time) · required

When the object was created.

Example: "2026-04-15T14:30:00Z"
updated_atstring (date-time) · required

When the object last changed.

Example: "2026-04-15T14:30:00Z"
400Malformed JSON, an unknown field, an empty body, a malformed id, or a URL that is not accepted.
errorobject · required

The error object of every /v1 error response. type, code, message, doc_url and request_id are always present.

Fields (7)
typestring · required

The 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_error
codestring · required

Machine-readable error code. Branch on this, not on message. Each code is documented at its doc_url.

Example: "amount_precision_invalid"
messagestring · required

Human-readable description for a developer. Never includes personal data or internal detail; a 5xx message is always generic.

Example: "CAD amounts allow 2 decimal places; got 3."
doc_urlstring (uri) · required

Where this code is documented.

Example: "https://docs.antonpayments.com/api-reference/errors#amount_precision_invalid"
request_idstring · required

The req_ ID of the request that failed; the same value as the Request-Id header.

Example: "req_01JD3XB7Q2"
paramstring

The request field or query parameter at fault, when one is. With several failures, see details.

Example: "amount"
detailsarray of object

Every field failure at once, so a form can be fixed in one pass.

Item fields (3)
paramstring · required

Dotted JSON path to the offending field.

Example: "amount"
codestring · required
Example: "amount_precision_invalid"
messagestring · required
Example: "CAD amounts allow 2 decimal places; got 3."
401Missing, expired or invalid credentials (access token or DPoP proof). Carries `WWW-Authenticate`.
errorobject · required

The error object of every /v1 error response. type, code, message, doc_url and request_id are always present.

Fields (7)
typestring · required

The 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_error
codestring · required

Machine-readable error code. Branch on this, not on message. Each code is documented at its doc_url.

Example: "amount_precision_invalid"
messagestring · required

Human-readable description for a developer. Never includes personal data or internal detail; a 5xx message is always generic.

Example: "CAD amounts allow 2 decimal places; got 3."
doc_urlstring (uri) · required

Where this code is documented.

Example: "https://docs.antonpayments.com/api-reference/errors#amount_precision_invalid"
request_idstring · required

The req_ ID of the request that failed; the same value as the Request-Id header.

Example: "req_01JD3XB7Q2"
paramstring

The request field or query parameter at fault, when one is. With several failures, see details.

Example: "amount"
detailsarray of object

Every field failure at once, so a form can be fixed in one pass.

Item fields (3)
paramstring · required

Dotted JSON path to the offending field.

Example: "amount"
codestring · required
Example: "amount_precision_invalid"
messagestring · required
Example: "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 · required

The error object of every /v1 error response. type, code, message, doc_url and request_id are always present.

Fields (7)
typestring · required

The 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_error
codestring · required

Machine-readable error code. Branch on this, not on message. Each code is documented at its doc_url.

Example: "amount_precision_invalid"
messagestring · required

Human-readable description for a developer. Never includes personal data or internal detail; a 5xx message is always generic.

Example: "CAD amounts allow 2 decimal places; got 3."
doc_urlstring (uri) · required

Where this code is documented.

Example: "https://docs.antonpayments.com/api-reference/errors#amount_precision_invalid"
request_idstring · required

The req_ ID of the request that failed; the same value as the Request-Id header.

Example: "req_01JD3XB7Q2"
paramstring

The request field or query parameter at fault, when one is. With several failures, see details.

Example: "amount"
detailsarray of object

Every field failure at once, so a form can be fixed in one pass.

Item fields (3)
paramstring · required

Dotted JSON path to the offending field.

Example: "amount"
codestring · required
Example: "amount_precision_invalid"
messagestring · required
Example: "CAD amounts allow 2 decimal places; got 3."
404No such subscription on your account (`resource_missing`).
errorobject · required

The error object of every /v1 error response. type, code, message, doc_url and request_id are always present.

Fields (7)
typestring · required

The 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_error
codestring · required

Machine-readable error code. Branch on this, not on message. Each code is documented at its doc_url.

Example: "amount_precision_invalid"
messagestring · required

Human-readable description for a developer. Never includes personal data or internal detail; a 5xx message is always generic.

Example: "CAD amounts allow 2 decimal places; got 3."
doc_urlstring (uri) · required

Where this code is documented.

Example: "https://docs.antonpayments.com/api-reference/errors#amount_precision_invalid"
request_idstring · required

The req_ ID of the request that failed; the same value as the Request-Id header.

Example: "req_01JD3XB7Q2"
paramstring

The request field or query parameter at fault, when one is. With several failures, see details.

Example: "amount"
detailsarray of object

Every field failure at once, so a form can be fixed in one pass.

Item fields (3)
paramstring · required

Dotted JSON path to the offending field.

Example: "amount"
codestring · required
Example: "amount_precision_invalid"
messagestring · required
Example: "CAD amounts allow 2 decimal places; got 3."
422An event type is unknown, `url` or `events` was `null`, or metadata is over its limits.
errorobject · required

The error object of every /v1 error response. type, code, message, doc_url and request_id are always present.

Fields (7)
typestring · required

The 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_error
codestring · required

Machine-readable error code. Branch on this, not on message. Each code is documented at its doc_url.

Example: "amount_precision_invalid"
messagestring · required

Human-readable description for a developer. Never includes personal data or internal detail; a 5xx message is always generic.

Example: "CAD amounts allow 2 decimal places; got 3."
doc_urlstring (uri) · required

Where this code is documented.

Example: "https://docs.antonpayments.com/api-reference/errors#amount_precision_invalid"
request_idstring · required

The req_ ID of the request that failed; the same value as the Request-Id header.

Example: "req_01JD3XB7Q2"
paramstring

The request field or query parameter at fault, when one is. With several failures, see details.

Example: "amount"
detailsarray of object

Every field failure at once, so a form can be fixed in one pass.

Item fields (3)
paramstring · required

Dotted JSON path to the offending field.

Example: "amount"
codestring · required
Example: "amount_precision_invalid"
messagestring · required
Example: "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 · required

The error object of every /v1 error response. type, code, message, doc_url and request_id are always present.

Fields (7)
typestring · required

The 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_error
codestring · required

Machine-readable error code. Branch on this, not on message. Each code is documented at its doc_url.

Example: "amount_precision_invalid"
messagestring · required

Human-readable description for a developer. Never includes personal data or internal detail; a 5xx message is always generic.

Example: "CAD amounts allow 2 decimal places; got 3."
doc_urlstring (uri) · required

Where this code is documented.

Example: "https://docs.antonpayments.com/api-reference/errors#amount_precision_invalid"
request_idstring · required

The req_ ID of the request that failed; the same value as the Request-Id header.

Example: "req_01JD3XB7Q2"
paramstring

The request field or query parameter at fault, when one is. With several failures, see details.

Example: "amount"
detailsarray of object

Every field failure at once, so a form can be fixed in one pass.

Item fields (3)
paramstring · required

Dotted JSON path to the offending field.

Example: "amount"
codestring · required
Example: "amount_precision_invalid"
messagestring · required
Example: "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 · required

The error object of every /v1 error response. type, code, message, doc_url and request_id are always present.

Fields (7)
typestring · required

The 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_error
codestring · required

Machine-readable error code. Branch on this, not on message. Each code is documented at its doc_url.

Example: "amount_precision_invalid"
messagestring · required

Human-readable description for a developer. Never includes personal data or internal detail; a 5xx message is always generic.

Example: "CAD amounts allow 2 decimal places; got 3."
doc_urlstring (uri) · required

Where this code is documented.

Example: "https://docs.antonpayments.com/api-reference/errors#amount_precision_invalid"
request_idstring · required

The req_ ID of the request that failed; the same value as the Request-Id header.

Example: "req_01JD3XB7Q2"
paramstring

The request field or query parameter at fault, when one is. With several failures, see details.

Example: "amount"
detailsarray of object

Every field failure at once, so a form can be fixed in one pass.

Item fields (3)
paramstring · required

Dotted JSON path to the offending field.

Example: "amount"
codestring · required
Example: "amount_precision_invalid"
messagestring · required
Example: "CAD amounts allow 2 decimal places; got 3."

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