Rotate the signing secret

Mints a new signing secret and returns it - the only other place a secret is ever visible. Scope: webhooks:manage.

Zero-downtime by design: for 24 hours every delivery’s webhook-signature header carries two space-delimited v1, signatures (old secret + new secret). Standard verification libraries accept any matching signature automatically, so deploy the new secret at your own pace within the window. After rotation_grace_ends_at, only the new secret signs.

Rotate immediately if a secret may have leaked; rotate periodically as hygiene.

POST /v1/webhook_endpoints/{id}/rotate_secret

Rotate the signing secret

cURL

curl --request POST \
  --url https://api.vexioncards.one/v1/webhook_endpoints/{id}/rotate_secret \
  --header 'Authorization: Bearer <token>' \
  --header 'Idempotency-Key: <idempotency-key>'

200

{
  "id": "whk_01HW9RBZ4GH7N8MTX1RVWHKDEF",
  "object": "webhook_endpoint",
  "url": "https://hooks.demo-coffee.example/vexion",
  "description": "Loyalty events to ERP",
  "enabled_events": [
    "customer.created",
    "customer.pass_installed",
    "transaction.created"
  ],
  "status": "enabled",
  "consecutive_failures": 0,
  "api_version": "2026-07",
  "created_at": 1750691700,
  "updated_at": 1750691700,
  "secret": "whsec_b3a9c2d4e6f8a0b1c2d3e4f5a6b7c8d9",
  "rotation_grace_ends_at": 1750778100
}

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 · required

Required on every POST, PUT, PATCH, and DELETE. 24-hour dedup window keyed on (api_key_id, idempotency_key). Up to 255 chars, [a-zA-Z0-9_-].

Maximum string length: 255

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

Path Parameters

id · string · required

Endpoint identifier (whk_ prefix).

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

Response

200

application/json

Rotated

The webhook endpoint INCLUDING its signing secret. Returned ONLY by POST /v1/webhook_endpoints (create) and POST .../rotate_secret. The secret never appears on any GET - if lost, 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 version all event payloads to this endpoint serialize against. Set at creation, immutable - create a new endpoint to move to a newer version. Decouples your receiver upgrade schedule from your request code.

Example:

"2026-07"

created_at · integer · required

Unix seconds.

Example:

1750691700

secret · string · required

The signing secret - whsec_ + base64 key material (Standard Webhooks format). Shown only in this response and on rotation - store it now; it is never retrievable again (lost = rotate). Verify deliveries with any standard-webhooks/svix library, or manually: HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw body} with the base64-decoded secret.

Pattern: ^whsec_[A-Za-z0-9+/_-]{32}$

Example:

"whsec_5f4dcc3b5aa765d61d8327deb882cf99"

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

rotation_grace_ends_at · integer | null

Until this unix time, deliveries carry BOTH signatures (old + new) space-delimited in webhook-signature - verify against either; no downtime. Null outside a rotation window.

Example:

1750778100