Update a webhook endpoint

Updates url, description, enabled_events, or status. URL changes re-run SSRF validation. api_version is immutable - create a new endpoint to move to a newer date version.

Setting status: "enabled" is also the API path for recovering an auto_disabled endpoint (after 50 consecutive failures or a 410 response). Investigate the receiver first - re-enabling without a fix just re-runs the failure curve.

Scope: webhooks:manage.

PATCH /v1/webhook_endpoints/{id}

cURL

Expand subscription

curl --request PATCH \
  --url https://api.vexioncards.one/v1/webhook_endpoints/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "enabled_events": [
    "customer.created",
    "customer.updated",
    "customer.pass_installed",
    "transaction.created",
    "transaction.reversed"
  ]
}
'

200

{
  "id": "whk_01J9MZX2Q4R8T6VBNM3KLP0D7S",
  "object": "webhook_endpoint",
  "url": "https://partner.example/webhooks/vexion",
  "enabled_events": [
    "transaction.created",
    "customer.created"
  ],
  "status": "enabled",
  "consecutive_failures": 0,
  "api_version": "2026-07",
  "created_at": 1750000000,
  "updated_at": 1752200000
}

Authorizations

Authorization · string · header · required

Your secret API key as a Bearer token: Authorization: Bearer vxn_sk_.... Keys are created and scoped in the dashboard - see Authentication.

Headers

Idempotency-Key · string

Recommended on PATCH and DELETE for safe retries.

Maximum string length: 255

Pattern: ^[a-zA-Z0-9_-]+$

Path Parameters

id · string · required

Endpoint identifier (whk_ prefix).

Pattern: ^whk_[A-Za-z0-9]+$

Body

application/json

Mutable fields: url, description, enabled_events, status. URL changes re-run SSRF validation. api_version is IMMUTABLE - create a new endpoint to move versions. Setting status: "enabled" is also how you recover an auto_disabled endpoint.

url · string<uri>

New delivery URL - re-runs SSRF validation.

description · string | null

New label, or null to clear.

Maximum string length: 200

enabled_events · (enum<string> | any)[]

Replacement subscription list (SET semantics).

Minimum array length: 1

What an endpoint SUBSCRIBES to: either one of the 22 catalog event names, or the wildcard * meaning every event, current and future.

This is deliberately distinct from WebhookEventName. A DELIVERED event always carries a concrete name, so * is never valid as WebhookEvent.type, WebhookDelivery.event_type, the event_type you send to POST /v1/webhook_endpoints/{id}/test, or the event_type filter on the deliveries list. It is valid ONLY inside enabled_events.

* must be sent alone: ["*", "customer.created"] returns 422 validation_failed.

Available options: customer.created, customer.updated, customer.deleted, customer.pass_installed, customer.pass_uninstalled, card.created, card.updated, card.deleted, custom_field.created, custom_field.updated, custom_field.deleted, product.created, product.updated, transaction.created, transaction.reversed, notification.sent, notification.delivery_updated, location.updated, team_member.added, team_member.updated, team_member.removed, webhook_endpoint.delivery_failed

Example:

"customer.created"

status · enum<string>

Toggle delivery. Setting enabled re-activates an auto_disabled endpoint (you cannot set auto_disabled yourself).

Available options: enabled, disabled

Response

200

application/json

Updated webhook endpoint (full object).

A registered outbound webhook receiver. Each endpoint is independently scoped (event subscription list), secured (own HMAC secret), paused, and monitored. The secret is NEVER present on GET - it is returned exactly once by create and rotate.

id · string · required

Endpoint identifier, whk_ prefixed opaque string. Never a database id.

Pattern: ^whk_[A-Za-z0-9]+$

Example:

"whk_01HW9RBZ4GH7N8MTX1RVWHKDEF"

object · string · required

Always "webhook_endpoint".

Allowed value: "webhook_endpoint"

url · string<uri> · required

HTTPS URL we POST events to. Validated against SSRF rules at registration AND re-validated per delivery attempt (DNS rebinding defense: every attempt re-resolves and re-checks the IP against the blocklist - no private ranges, no cloud metadata endpoints, no localhost).

Example:

"https://hooks.demo-coffee.example/vexion"

enabled_events · (enum<string> | any)[] · required

Explicit array of event names from the 22-event catalog. The wildcard ["*"] subscribes to every current AND future event - we recommend explicit names so a new event does not surprise your receiver.

What an endpoint SUBSCRIBES to: either one of the 22 catalog event names, or the wildcard * meaning every event, current and future.

This is deliberately distinct from WebhookEventName. A DELIVERED event always carries a concrete name, so * is never valid as WebhookEvent.type, WebhookDelivery.event_type, the event_type you send to POST /v1/webhook_endpoints/{id}/test, or the event_type filter on the deliveries list. It is valid ONLY inside enabled_events.

* must be sent alone: ["*", "customer.created"] returns 422 validation_failed.

Available options: customer.created, customer.updated, customer.deleted, customer.pass_installed, customer.pass_uninstalled, card.created, card.updated, card.deleted, custom_field.created, custom_field.updated, custom_field.deleted, product.created, product.updated, transaction.created, transaction.reversed, notification.sent, notification.delivery_updated, location.updated, team_member.added, team_member.updated, team_member.removed, webhook_endpoint.delivery_failed

Example:

"customer.created"

Example:

[
  "customer.created",
  "customer.pass_installed",
  "transaction.created"
]

status · enum<string> · required

enabled/disabled are merchant-toggled. auto_disabled is set by the platform after 50 consecutive failures OR a single 410 Gone response - requires explicit re-enable (dashboard or PATCH with status: "enabled"), forcing investigation before more events flow.

Available options: enabled, disabled, auto_disabled

Example:

"enabled"

consecutive_failures · integer · required

Consecutive FAILED delivery attempts across every event to this endpoint, reset to 0 on any successful delivery. The platform auto-disables the endpoint (status flips to auto_disabled) once this reaches 50, OR instantly on a single 410 Gone response regardless of this count. Watch this to alert before auto-disable happens rather than after.

Required range: x >= 0

Example:

0

api_version · string · required

Date-based API version all event payloads to this endpoint serialize against - pinned at creation, immutable (a live consumer's payload shape never changes under it). The platform launches on 2026-07; when a new version ships, upgrade with zero downtime: create a second endpoint on the new version, verify with the test endpoint, cut your consumer over, delete the old one.

Example:

"2026-07"

created_at · integer · required

Unix seconds.

Example:

1750691700

description · string | null

Free-text merchant-facing label. Optional.

Maximum string length: 200

Example:

"Loyalty events to ERP"

updated_at · integer

Unix seconds of last change.

Example:

1750691700