> ## 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. # List events > Account-wide feed of domain events that fanned out to at least one enabled webhook endpoint, newest first. Each row carries the same envelope content a subscribed receiver was pushed - useful for reconciliation, backfilling a receiver that was down, or building your own audit trail without inspecting every endpoint's deliveries individually. **This feed only contains events that had a live, enabled subscriber at the moment they fired.** An event emitted while your organization had zero enabled webhook endpoints is never recorded here - registering your first endpoint does not retroactively surface earlier activity. Filters: `type` (catalog event name) and `created_after`/`created_before` (unix seconds, inclusive). Scope: `webhooks:read` - this endpoint now carries its own least-privilege scope (previously it rode the coarser `webhooks:manage`, the pre-2026-08-02 registry's documented least-privilege caveat for this exact route). ## OpenAPI ````yaml /openapi.json get /v1/events 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/events: get: tags: - Events summary: List events description: >- Account-wide feed of domain events that fanned out to at least one enabled webhook endpoint, newest first. Each row carries the same envelope content a subscribed receiver was pushed - useful for reconciliation, backfilling a receiver that was down, or building your own audit trail without inspecting every endpoint's deliveries individually. **This feed only contains events that had a live, enabled subscriber at the moment they fired.** An event emitted while your organization had zero enabled webhook endpoints is never recorded here - registering your first endpoint does not retroactively surface earlier activity. Filters: `type` (catalog event name) and `created_after`/`created_before` (unix seconds, inclusive). Scope: `webhooks:read` - this endpoint now carries its own least-privilege scope (previously it rode the coarser `webhooks:manage`, the pre-2026-08-02 registry's documented least-privilege caveat for this exact route). operationId: listEvents parameters: - name: type in: query description: Filter by catalog event name. required: false schema: $ref: '#/components/schemas/WebhookEventName' - name: created_after in: query description: Only events at or after this time (inclusive). required: false schema: anyOf: - type: integer title: Unix seconds - type: string format: date-time title: ISO-8601 - name: created_before in: query description: Only events at or before this time (inclusive). required: false schema: anyOf: - type: integer title: Unix seconds - type: string format: date-time title: ISO-8601 - name: limit in: query required: false description: Page size, 1-100. Default 25. schema: type: integer minimum: 1 maximum: 100 default: 25 - name: starting_after in: query description: >- Walk forward. Send the last id from the previous page's data[]. Numeric offset or page parameters are not supported; cursors are the only supported paging mechanism. required: false schema: type: string pattern: ^evt_[A-Za-z0-9]+$ - name: ending_before in: query description: Walk backward. Send the first id from the current page's data[]. required: false schema: type: string pattern: ^evt_[A-Za-z0-9]+$ responses: '200': description: Paginated event list. content: application/json: schema: $ref: '#/components/schemas/EventList' examples: Events: summary: Two recent events value: object: list data: - id: evt_01HW9RDZ4JK7N8MTX1RVEVTDEF object: event type: transaction.created created_at: 1750691720 data: object: id: txn_01HW9RCZ4HJ7N8MTX1RVWHDDEF object: transaction - id: evt_01HW9RDZ4JK7N8MTX1RVEVTDEH object: event type: customer.updated created_at: 1750691600 data: object: id: cus_01HW9RCZ4HJ7N8MTX1RVWHDMAG object: customer previous_attributes: first_name: Jan request: id: req_01HW9RDZ4JK7N8MTX1RVREQDEF idempotency_key: null has_more: false url: /v1/events headers: {} '400': description: >- Invalid pagination parameter: limit outside 1-100, a malformed cursor, or an invalid date. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Invalid limit: summary: limit out of range value: error: type: invalid_request_error code: invalid_limit message: limit must be an integer between 1 and 100. doc_url: >- https://vexioncards.mintlify.site/api-reference/errors#invalid_limit request_id: req_5f8b2c4a9e1d3 param: limit Malformed cursor: summary: starting_after is not a valid evt_ cursor value: error: type: invalid_request_error code: invalid_cursor message: starting_after is not a valid evt_ cursor. doc_url: >- https://vexioncards.mintlify.site/api-reference/errors#invalid_cursor request_id: req_5f8b2c4a9e1d3 param: starting_after headers: {} '401': description: Missing, invalid, or revoked API key. content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Key lacks the required scope (webhooks:read). 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: 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 EventList: allOf: - $ref: '#/components/schemas/ListEnvelope' - type: object properties: data: type: array items: $ref: '#/components/schemas/Event' 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. ListEnvelope: type: object required: - object - data - has_more properties: object: type: string const: list description: Always `"list"`. data: type: array items: {} description: Array of the requested resource type. has_more: type: boolean description: >- True when more pages exist - pass the last item id as `starting_after`. next_cursor: type: - string - 'null' description: >- Cursor for the next page **in the direction you are already paging**, or `null` when this page ends the collection. `has_more: true` always comes with a non-null `next_cursor`. Feed it back to the SAME parameter you used: `starting_after` when paging forward (the default), or `ending_before` when paging backward. Treat it as opaque and do not parse it. You no longer need to take the last object's `id` yourself. That still works and is unchanged, but deriving the cursor from the page put the burden of knowing the sort direction on you, and it broke silently on any endpoint whose cursor is not the object id. example: cus_iofv5j4hn6bphinmmyat27tc5y url: type: string description: Stable collection URL. description: >- Standard cursor-pagination envelope for list endpoints. See the Pagination guide. Event: type: object description: >- One row of the account-wide GET /v1/events feed - a domain event that fanned out to at least one enabled webhook endpoint. Deliberately narrower than the WebhookEvent delivery envelope: it carries no `api_version`, since that is pinned PER ENDPOINT and one event can fan out to endpoints on different pinned versions. Events emitted while your organization had zero enabled webhook endpoints are never recorded here - see the operation description. required: - id - object - type - created_at - data properties: id: type: string pattern: ^evt_[A-Za-z0-9]+$ description: >- Event ULID. The same id every delivery of this event to every subscribed endpoint carries as its `webhook-id`. example: evt_01HW9RDZ4JK7N8MTX1RVEVTDEF object: type: string const: event description: Always `"event"`. type: $ref: '#/components/schemas/WebhookEventName' created_at: type: integer description: Unix seconds, UTC - when the event fired. example: 1750691720 data: type: object required: - object description: The payload. properties: object: type: object description: >- Full sanitized resource snapshot at the time the event fired - the same `data.object` a subscribed receiver was pushed. previous_attributes: type: object description: >- Diff of allowlisted public fields with their PRIOR values. Present only on `*.updated` events. request: type: object description: >- Present when the event was caused by an API call; omitted for server-emitted events (POS webhooks, cron jobs, wallet callbacks). properties: id: type: string description: The originating request id. example: req_01HW9RDZ4JK7N8MTX1RVREQDEF idempotency_key: type: - string - 'null' description: The Idempotency-Key the caller sent, if any. 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.