Webhook event delivery

The envelope this API sends for EVERY webhook event, regardless of which event fired it - see the WebhookEventName enum for the full catalog (customer., card., transaction., notification., location.updated, team_member., webhook_endpoint.delivery_failed, custom_field., product.*). One generic operation documents the shared envelope shape (id, object, type, created_at, api_version, data, request) rather than duplicating an identical requestBody once per catalog event; data.object carries the actual resource snapshot and its concrete shape is documented on that resource’s own schema elsewhere in this spec. See the webhooks guide for delivery, retry, and signature-verification details.

WEBHOOK event

Example

{
  "id": "evt_01HW9RDZ4JK7N8MTX1RVEVTDEF",
  "object": "event",
  "type": "transaction.created",
  "created_at": 1750691720,
  "api_version": "2026-07",
  "data": {
    "object": {},
    "previous_attributes": {}
  },
  "request": {
    "id": "req_01HW9RDZ4JK7N8MTX1RVREQDEF",
    "idempotency_key": "<string>"
  }
}

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.

Body

application/json

The delivery envelope every webhook POST carries - Stripe-shaped: data.object is the full resource as of the event, type is the catalog name, api_version matches the endpoint's pinned version. Dedupe by id (identical across endpoints and retries).

id · string · required

Event ULID. Stable across retries - dedup on this.

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

Example:

"evt_01HW9RDZ4JK7N8MTX1RVEVTDEF"

object · string · required

Always "event".

Allowed value: "event"

type · enum<string> · required

The locked v1 event catalog - 22 events across 9 subjects. Names follow resource.action with past-participle actions (transaction.created), never the dotted verb-stems used by transaction types - the two vocabularies never mix. product.created/product.updated fire for dashboard and API-created catalog changes; POS-synced catalog changes do not emit (they mirror the till, and a first sync would flood your endpoint).

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:

"transaction.created"

created_at · integer · required

Unix seconds, UTC - when the event fired (not when this attempt was sent).

Example:

1750691720

api_version · string · required

The endpoint's pinned date version (NOT the triggering request's version).

Example:

"2026-07"

data · object · required

The payload.

Show child attributes

request · object | null

Present when the event was caused by an API call; omitted for server-emitted events (POS webhooks, cron jobs, wallet callbacks).

Show child attributes

Response

200

Return any 2xx status to acknowledge receipt. A non-2xx response (or no response within the timeout) is retried on the documented backoff schedule.