> ## Documentation Index > Fetch the complete documentation index at: https://vexioncards.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Create a webhook endpoint > ## Delivery retries Failed deliveries are retried up to **12 attempts** over roughly 24 hours with **exponential backoff and +/-20% jitter**. Delay before each retry: 30s, 1m, 2m, 5m, 15m, 30m, 1h, 2h, 4h, 8h, 8h (the ladder totals 23h53m30s before jitter). A response with any 2xx status counts as delivered; anything else (including timeouts after 10s) schedules the next attempt. When an event exhausts all attempts the delivery is marked `failed`, and repeated failures disable the endpoint automatically. `webhook_endpoint.delivery_failed` is sent to your OTHER endpoints, never to the endpoint whose delivery failed. ## Ordering and idempotency Events are NOT guaranteed to arrive in order, and any event may be delivered more than once (a retry after a slow response, or a redelivery). De-duplicate on the `webhook-id` header - the stable event id, identical across every retry of one event - and order by the payload `created_at` timestamp. Make your handler idempotent: processing the same event id twice must be a no-op. Registers an HTTPS receiver for outbound events. Scope: `webhooks:manage`. Rate limit: 10 creations/hour. **The `secret` is returned exactly once** - in this response and nowhere else. Store it immediately; if lost, rotate. ## Registration checks - **SSRF validation** - public DNS only, no private/reserved ranges, no cloud metadata endpoints, no localhost (`422 webhook_url_invalid`) - **URL text** - at most 2,048 characters, no user name or password, no spaces, control characters or backslashes (`422 webhook_url_invalid`). The same check runs on `PATCH` when you send a new `url` - **Event catalog check** - unknown names in `enabled_events` return `422 webhook_event_unknown` - **Reachability probe** - one HEAD request at create; DNS/TLS failures are hard errors (`422 webhook_url_unreachable`), non-2xx is tolerated ## What your receiver must do Verify the HMAC on every request, enforce the 5-minute anti-replay window, dedup on the event id, and ack within 10 seconds. Full verification code + retry schedule in [Webhooks](/api-reference/webhooks). ## How deliveries are signed (Standard Webhooks) Every delivery is a `POST` with three headers - the [Standard Webhooks](https://www.standardwebhooks.com) scheme, the same one Svix-based platforms use, so you can verify with any off-the-shelf `standard-webhooks` / `svix` library: ``` webhook-id: evt_01HW9RDZ4JK7N8MTX1RVEVTDEF webhook-timestamp: 1750691720 webhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4= ``` - Signed content: `{webhook-id}.{webhook-timestamp}.{raw body}` - exact bytes, no normalization - Algorithm: HMAC-SHA256, key = the base64-decoded part of your `whsec_...` secret - Reject timestamps older than **5 minutes** (replay protection) - During the 24 h rotation grace the header carries TWO space-delimited `v1,` signatures (old + new) - accept if ANY matches; rotation needs no code change on your side Full verification guide with code samples: [Webhooks](/api-reference/webhooks). ## Delivery contract - **At-least-once, no ordering guarantee** - dedupe by envelope `id`, never assume sequence (fetch current state via the API when order matters) - Your receiver must return **2xx within 10 seconds** - defer real work to a queue; anything else (timeouts, 3xx, 4xx, 5xx) counts as failed - Failed deliveries retry **12 times across ~24 hours** (exponential backoff + jitter - full table in the [Webhooks guide](/api-reference/webhooks)); after the last attempt the delivery is `failed` and `webhook_endpoint.delivery_failed` fires to your OTHER endpoints - **Auto-disable:** 50 consecutive failures, or a single `HTTP 410 Gone`, sets `status: "auto_disabled"`; re-enable with `PATCH status: "enabled"` (missed events are not replayed - reconcile via list endpoints) - Subscribe narrowly (`enabled_events`) - fewer events, less load, and you can always widen later ## Multiple endpoints, duplicate URLs, limits - Up to **16 endpoints** per organization (`409 webhook_endpoint_limit_reached`) - Stripe's proven ceiling - **Duplicate URLs are allowed** and each endpoint is independent (own secret, own subscriptions, own version). Two endpoints on the same URL with overlapping `enabled_events` means your receiver gets the event **twice, with different signatures** - legitimate when splitting event subsets or migrating API versions, otherwise narrow the subscriptions. Your dedupe key is the envelope `id`, which is identical across both deliveries - api_version is pinned per endpoint at creation - version migration = new endpoint on the new version, test, cut over, delete the old ## OpenAPI ````yaml /openapi.json post /v1/webhook_endpoints openapi: 3.1.0 info: title: VEXiON cards Public API description: >- ## Rate limiting Two independent layers, checked in this order: 1. **Per-IP throttle (pre-authentication).** Applied to every `/v1` request BEFORE the API key is checked, keyed on the caller's IP address: - **600 requests/minute** per IP - a flood ceiling, `429 rate_limit_error` / `rate_limited`. - **20 failed authentications per 15 minutes** per IP - a key-guessing ceiling. Only responses that are `401` (missing/invalid/revoked key) count against this ceiling; a `403` from a valid key that simply lacks a scope does not. `429 rate_limit_error` / `too_many_failed_attempts`. Both ceilings send `Retry-After` (seconds). 2. **Per-key, per-bucket limiter (post-authentication).** Documented per endpoint (see each operation's `429` response and the `rate_limit` field on the API Key resource) - e.g. 60/min default, 120/min for transactions, plus the notification-broadcast and lookup-filter buckets described on their own endpoints. ### Rate-limit response headers Every rate-limited response carries the legacy `X-RateLimit-Limit` / `X-RateLimit-Remaining` / `X-RateLimit-Reset` family (the last is an **epoch timestamp**) AND the IETF standards-track headers, side by side: - `RateLimit-Policy: "";q=;w=` - the static policy for the bucket that was hit. - `RateLimit: "";r=;t=` - live state. **`t` is a DURATION (seconds remaining), not the epoch timestamp `X-RateLimit-Reset` carries - the two are never the same value.** version: 1.0.0 servers: - url: https://api.vexioncards.one description: Production - url: https://migration.api.vexioncards.one description: Sandbox security: - apiKey: [] tags: - name: Customers - name: Cards - name: Transactions - name: Notifications - name: Locations - name: Products - name: API keys - name: Organization - name: Webhook endpoints - name: Events - name: Custom fields - name: Team members - name: Icons paths: /v1/webhook_endpoints: post: tags: - Webhook endpoints summary: Create a webhook endpoint description: >- ## Delivery retries Failed deliveries are retried up to **12 attempts** over roughly 24 hours with **exponential backoff and +/-20% jitter**. Delay before each retry: 30s, 1m, 2m, 5m, 15m, 30m, 1h, 2h, 4h, 8h, 8h (the ladder totals 23h53m30s before jitter). A response with any 2xx status counts as delivered; anything else (including timeouts after 10s) schedules the next attempt. When an event exhausts all attempts the delivery is marked `failed`, and repeated failures disable the endpoint automatically. `webhook_endpoint.delivery_failed` is sent to your OTHER endpoints, never to the endpoint whose delivery failed. ## Ordering and idempotency Events are NOT guaranteed to arrive in order, and any event may be delivered more than once (a retry after a slow response, or a redelivery). De-duplicate on the `webhook-id` header - the stable event id, identical across every retry of one event - and order by the payload `created_at` timestamp. Make your handler idempotent: processing the same event id twice must be a no-op. Registers an HTTPS receiver for outbound events. Scope: `webhooks:manage`. Rate limit: 10 creations/hour. **The `secret` is returned exactly once** - in this response and nowhere else. Store it immediately; if lost, rotate. ## Registration checks - **SSRF validation** - public DNS only, no private/reserved ranges, no cloud metadata endpoints, no localhost (`422 webhook_url_invalid`) - **URL text** - at most 2,048 characters, no user name or password, no spaces, control characters or backslashes (`422 webhook_url_invalid`). The same check runs on `PATCH` when you send a new `url` - **Event catalog check** - unknown names in `enabled_events` return `422 webhook_event_unknown` - **Reachability probe** - one HEAD request at create; DNS/TLS failures are hard errors (`422 webhook_url_unreachable`), non-2xx is tolerated ## What your receiver must do Verify the HMAC on every request, enforce the 5-minute anti-replay window, dedup on the event id, and ack within 10 seconds. Full verification code + retry schedule in [Webhooks](/api-reference/webhooks). ## How deliveries are signed (Standard Webhooks) Every delivery is a `POST` with three headers - the [Standard Webhooks](https://www.standardwebhooks.com) scheme, the same one Svix-based platforms use, so you can verify with any off-the-shelf `standard-webhooks` / `svix` library: ``` webhook-id: evt_01HW9RDZ4JK7N8MTX1RVEVTDEF webhook-timestamp: 1750691720 webhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4= ``` - Signed content: `{webhook-id}.{webhook-timestamp}.{raw body}` - exact bytes, no normalization - Algorithm: HMAC-SHA256, key = the base64-decoded part of your `whsec_...` secret - Reject timestamps older than **5 minutes** (replay protection) - During the 24 h rotation grace the header carries TWO space-delimited `v1,` signatures (old + new) - accept if ANY matches; rotation needs no code change on your side Full verification guide with code samples: [Webhooks](/api-reference/webhooks). ## Delivery contract - **At-least-once, no ordering guarantee** - dedupe by envelope `id`, never assume sequence (fetch current state via the API when order matters) - Your receiver must return **2xx within 10 seconds** - defer real work to a queue; anything else (timeouts, 3xx, 4xx, 5xx) counts as failed - Failed deliveries retry **12 times across ~24 hours** (exponential backoff + jitter - full table in the [Webhooks guide](/api-reference/webhooks)); after the last attempt the delivery is `failed` and `webhook_endpoint.delivery_failed` fires to your OTHER endpoints - **Auto-disable:** 50 consecutive failures, or a single `HTTP 410 Gone`, sets `status: "auto_disabled"`; re-enable with `PATCH status: "enabled"` (missed events are not replayed - reconcile via list endpoints) - Subscribe narrowly (`enabled_events`) - fewer events, less load, and you can always widen later ## Multiple endpoints, duplicate URLs, limits - Up to **16 endpoints** per organization (`409 webhook_endpoint_limit_reached`) - Stripe's proven ceiling - **Duplicate URLs are allowed** and each endpoint is independent (own secret, own subscriptions, own version). Two endpoints on the same URL with overlapping `enabled_events` means your receiver gets the event **twice, with different signatures** - legitimate when splitting event subsets or migrating API versions, otherwise narrow the subscriptions. Your dedupe key is the envelope `id`, which is identical across both deliveries - api_version is pinned per endpoint at creation - version migration = new endpoint on the new version, test, cut over, delete the old operationId: createWebhookEndpoint parameters: - name: Idempotency-Key in: header description: >- 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_-]. required: true example: a4c2d496-a734-4bc0-868a-443fccbacab8 schema: type: string maxLength: 255 pattern: ^[a-zA-Z0-9_-]+$ requestBody: content: application/json: schema: $ref: '#/components/schemas/WebhookEndpointCreateRequest' examples: ERP integration: summary: Explicit event subscription (recommended) value: url: https://hooks.demo-coffee.example/vexion description: Loyalty events to ERP enabled_events: - customer.created - customer.pass_installed - transaction.created Subscribe to everything: summary: Wildcard - includes future events value: url: https://hooks.demo-coffee.example/vexion-all enabled_events: - '*' required: true responses: '201': description: Created. The plaintext secret is returned exactly once. content: application/json: schema: $ref: '#/components/schemas/WebhookEndpointWithSecret' examples: Created with secret: summary: secret shown ONCE value: 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_5f4dcc3b5aa765d61d8327deb882cf99 headers: {} '400': description: >- Malformed body, missing required field, or missing Idempotency-Key header. content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Missing, invalid, or revoked API key. content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Key lacks the required scope (webhooks:manage). content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: >- Webhook endpoint limit reached (16 per organization), or Idempotency-Key reuse with a different body. content: application/json: schema: $ref: '#/components/schemas/Error' '413': description: >- Request body exceeds the 1 MB cap. The body was never parsed, so the request had no effect. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: type: invalid_request_error code: request_too_large message: The request body exceeds the maximum allowed size. doc_url: >- https://vexioncards.mintlify.site/api-reference/errors#request_too_large request_id: req_5f8b2c4a9e1d3 '422': description: Validation failure (single or multi-field). content: application/json: schema: $ref: '#/components/schemas/Error' examples: SSRF rejected: summary: URL resolves to a private range value: error: type: invalid_request_error code: webhook_url_invalid message: >- URL resolves to a private IP range and cannot be registered request_id: req_x1 Unknown event: summary: Name not in the 22-event catalog value: error: type: invalid_request_error code: webhook_event_unknown message: '''transaction.settled'' is not in the event catalog' param: enabled_events[1] request_id: req_x2 headers: {} '429': description: Rate limited - respect Retry-After. content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Server error. Retry-safe on idempotent calls. content: application/json: schema: $ref: '#/components/schemas/Error' example: 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 examples: Http 500 default: summary: Http 500 default value: 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 headers: {} deprecated: false components: schemas: WebhookEndpointCreateRequest: type: object description: >- Register a new outbound endpoint. Scope: `webhooks:manage`. The response includes the signing `secret` exactly once. Registration runs SSRF validation (https only; private, loopback and reserved ranges rejected, including DNS-rebinding re-checks on the resolved address) plus a single HEAD reachability probe (any HTTP status is accepted; a DNS/TLS/connection failure is rejected as webhook_url_unreachable). Rate limit: 10 endpoint creations per hour. required: - url - enabled_events properties: url: type: string format: uri description: >- HTTPS URL to deliver events to. Must pass SSRF validation: public DNS, no private/reserved IP ranges, no cloud metadata endpoints, publicly-trusted TLS in live mode. example: https://hooks.demo-coffee.example/vexion description: type: - string - 'null' maxLength: 200 description: Optional merchant-facing label. example: Loyalty events to ERP enabled_events: type: array minItems: 1 items: $ref: '#/components/schemas/WebhookEventSubscription' description: >- Event names to subscribe to, or `["*"]` for everything (current + future). Unknown names return `422 webhook_event_unknown`. example: - customer.created - transaction.created WebhookEndpointWithSecret: type: object description: >- 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. required: - id - object - url - enabled_events - status - consecutive_failures - secret - api_version - created_at properties: id: type: string pattern: ^whk_[A-Za-z0-9]+$ description: >- Endpoint identifier, `whk_` prefixed opaque string. Never a database id. example: whk_01HW9RBZ4GH7N8MTX1RVWHKDEF object: type: string const: webhook_endpoint description: Always `"webhook_endpoint"`. url: type: string format: uri description: >- 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 description: type: - string - 'null' maxLength: 200 description: Free-text merchant-facing label. Optional. example: Loyalty events to ERP enabled_events: type: array items: $ref: '#/components/schemas/WebhookEventSubscription' description: >- 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. example: - customer.created - customer.pass_installed - transaction.created status: type: string enum: - enabled - disabled - auto_disabled description: >- `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. example: enabled consecutive_failures: type: integer minimum: 0 description: >- 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. example: 0 api_version: type: string description: >- 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: type: integer description: Unix seconds. example: 1750691700 updated_at: type: integer description: Unix seconds of last change. example: 1750691700 secret: type: string pattern: ^whsec_[A-Za-z0-9+/_-]{32}$ description: >- 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. example: whsec_5f4dcc3b5aa765d61d8327deb882cf99 rotation_grace_ends_at: type: - integer - 'null' description: >- 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 Error: type: object required: - error properties: error: type: object required: - type - code - message properties: type: type: string enum: - invalid_request_error - authentication_error - permission_error - not_found_error - rate_limit_error - idempotency_error - api_error code: type: string message: type: string retry_after: type: integer description: >- Seconds to wait before retrying. Present on rate-limit (429) and idempotency-key-in-use (409) errors; mirrors the `Retry-After` HTTP header. Absent on error types that carry no retry guidance. example: 5 param: type: - string - 'null' request_id: type: string doc_url: type: string format: uri field_errors: type: array description: >- Per-field errors on a 422. At most 100 entries: a request with more errors gets the first 100. items: type: object properties: param: type: string code: type: string message: type: string expected_currency: type: string description: >- On `currency_mismatch`: the business currency the request must use. Absent on every other field error. description: >- The error payload: type (category), code (machine-readable), message (human-readable), retry_after (seconds, on rate-limit/idempotency-in-use errors only), param (offending field), request_id, doc_url, field_errors[]. description: >- Standard error envelope. Branch on `error.code`; include `error.request_id` in support requests. See the Errors guide. WebhookEventSubscription: description: >- 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`. anyOf: - $ref: '#/components/schemas/WebhookEventName' - const: '*' title: All events (current and future) example: customer.created WebhookEventName: type: string enum: - 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 description: >- 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). example: transaction.created securitySchemes: apiKey: type: http scheme: bearer description: >- Your secret API key as a Bearer token: `Authorization: Bearer vxn_sk_...`. Keys are created and scoped in the dashboard - see [Authentication](/api-reference/introduction#authentication). ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.