Webhook endpoints

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

webhook_endpoints

{id}

rotate_secret

Rotate the signing secret

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

const options = {
  method: 'POST',
  headers: {'Idempotency-Key': '<idempotency-key>', Authorization: 'Bearer <token>'}
};

fetch('https://api.vexioncards.one/v1/webhook_endpoints/{id}/rotate_secret', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.vexioncards.one/v1/webhook_endpoints/{id}/rotate_secret"

headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>"
}

response = requests.post(url, headers=headers)

print(response.text)

{
  "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
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "<string>",
    "message": "<string>",
    "retry_after": 5,
    "param": "<string>",
    "request_id": "<string>",
    "doc_url": "<string>",
    "field_errors": [
      {
        "param": "<string>",
        "code": "<string>",
        "message": "<string>",
        "expected_currency": "<string>"
      }
    ]
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "<string>",
    "message": "<string>",
    "retry_after": 5,
    "param": "<string>",
    "request_id": "<string>",
    "doc_url": "<string>",
    "field_errors": [
      {
        "param": "<string>",
        "code": "<string>",
        "message": "<string>",
        "expected_currency": "<string>"
      }
    ]
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "<string>",
    "message": "<string>",
    "retry_after": 5,
    "param": "<string>",
    "request_id": "<string>",
    "doc_url": "<string>",
    "field_errors": [
      {
        "param": "<string>",
        "code": "<string>",
        "message": "<string>",
        "expected_currency": "<string>"
      }
    ]
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "<string>",
    "message": "<string>",
    "retry_after": 5,
    "param": "<string>",
    "request_id": "<string>",
    "doc_url": "<string>",
    "field_errors": [
      {
        "param": "<string>",
        "code": "<string>",
        "message": "<string>",
        "expected_currency": "<string>"
      }
    ]
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "<string>",
    "message": "<string>",
    "retry_after": 5,
    "param": "<string>",
    "request_id": "<string>",
    "doc_url": "<string>",
    "field_errors": [
      {
        "param": "<string>",
        "code": "<string>",
        "message": "<string>",
        "expected_currency": "<string>"
      }
    ]
  }
}

{
  "error": {
    "type": "api_error",
    "code": "internal_error",
    "message": "An internal error occurred. The request may be retried with the same Idempotency-Key.",
    "doc_url": "https://vexioncards.mintlify.site/api-reference/errors#internal_error",
    "request_id": "req_5f8b2c4a9e1d3"
  }
}

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

string

required

Endpoint identifier (whk_ prefix).

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

Response

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.

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

Rotate the signing secret

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

const options = {
  method: 'POST',
  headers: {'Idempotency-Key': '<idempotency-key>', Authorization: 'Bearer <token>'}
};

fetch('https://api.vexioncards.one/v1/webhook_endpoints/{id}/rotate_secret', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.vexioncards.one/v1/webhook_endpoints/{id}/rotate_secret"

headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>"
}

response = requests.post(url, headers=headers)

print(response.text)

{
  "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
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "<string>",
    "message": "<string>",
    "retry_after": 5,
    "param": "<string>",
    "request_id": "<string>",
    "doc_url": "<string>",
    "field_errors": [
      {
        "param": "<string>",
        "code": "<string>",
        "message": "<string>",
        "expected_currency": "<string>"
      }
    ]
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "<string>",
    "message": "<string>",
    "retry_after": 5,
    "param": "<string>",
    "request_id": "<string>",
    "doc_url": "<string>",
    "field_errors": [
      {
        "param": "<string>",
        "code": "<string>",
        "message": "<string>",
        "expected_currency": "<string>"
      }
    ]
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "<string>",
    "message": "<string>",
    "retry_after": 5,
    "param": "<string>",
    "request_id": "<string>",
    "doc_url": "<string>",
    "field_errors": [
      {
        "param": "<string>",
        "code": "<string>",
        "message": "<string>",
        "expected_currency": "<string>"
      }
    ]
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "<string>",
    "message": "<string>",
    "retry_after": 5,
    "param": "<string>",
    "request_id": "<string>",
    "doc_url": "<string>",
    "field_errors": [
      {
        "param": "<string>",
        "code": "<string>",
        "message": "<string>",
        "expected_currency": "<string>"
      }
    ]
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "<string>",
    "message": "<string>",
    "retry_after": 5,
    "param": "<string>",
    "request_id": "<string>",
    "doc_url": "<string>",
    "field_errors": [
      {
        "param": "<string>",
        "code": "<string>",
        "message": "<string>",
        "expected_currency": "<string>"
      }
    ]
  }
}

{
  "error": {
    "type": "api_error",
    "code": "internal_error",
    "message": "An internal error occurred. The request may be retried with the same Idempotency-Key.",
    "doc_url": "https://vexioncards.mintlify.site/api-reference/errors#internal_error",
    "request_id": "req_5f8b2c4a9e1d3"
  }
}

API Reference

MCP server

Customers

Cards

Transactions

Products

Notifications

Locations

Team members

Custom fields

Events

Webhook endpoints

API keys

Organization

Icons

API Reference

Rotate the signing secret

Authorizations

Headers

Path Parameters

Response