> ## 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. # 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. ## OpenAPI ````yaml /openapi.json post /v1/webhook_endpoints/{id}/rotate_secret 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/{id}/rotate_secret: post: tags: - Webhook endpoints summary: Rotate the signing secret description: >- 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. operationId: rotateWebhookEndpointSecret parameters: - name: id in: path description: Endpoint identifier (`whk_` prefix). required: true example: whk_4crd3hu6mm2nydl7yhaji24dii schema: type: string pattern: ^whk_[A-Za-z0-9]+$ - 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: 89747164-791c-4b73-9fab-da1bbc69b6ab schema: type: string maxLength: 255 pattern: ^[a-zA-Z0-9_-]+$ responses: '200': description: Rotated content: application/json: schema: $ref: '#/components/schemas/WebhookEndpointWithSecret' examples: Rotated: summary: New secret + grace deadline 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_b3a9c2d4e6f8a0b1c2d3e4f5a6b7c8d9 rotation_grace_ends_at: 1750778100 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' '404': description: Resource not found in your organization. content: application/json: schema: $ref: '#/components/schemas/Error' '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: 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.