> ## Documentation Index
> Fetch the complete documentation index at: https://docs.byzantine.fi/llms.txt
> Use this file to discover all available pages before exploring further.

# Lists persisted lifecycle events owned by the authenticated integrator, newest first.



## OpenAPI

````yaml /api-reference/openapi-integrator.json get /v1/query/events
openapi: 3.0.3
info:
  title: Byzantine Integrator API
  description: Byzantine REST API for integrators.
  license:
    name: ''
  version: 0.2.0
servers:
  - url: https://sandbox.api.byzantine.fi
    description: Sandbox
security: []
tags:
  - name: API health
    description: Check API status.
  - name: Customer management
    description: Endpoints to create, update, and retrieve customer information.
  - name: Account management
    description: Endpoints to manage accounts, bank accounts, invitations, and user roles.
  - name: Products
    description: Endpoints to get data about products and vaults.
  - name: Transactions
    description: Endpoints to create and manage transactions.
  - name: OTP authentication
    description: Endpoints to initialize and manage user authentication with OTP.
  - name: Events
    description: Endpoints to list lifecycle events.
  - name: Webhooks
    description: Integrator-managed outbound webhook subscriptions and delivery history.
  - name: Integrator key management
    description: >-
      Endpoints to inspect the current integrator credential scope, create,
      update and delete integrator keys.
paths:
  /v1/query/events:
    get:
      tags:
        - Events
      summary: >-
        Lists persisted lifecycle events owned by the authenticated integrator,
        newest first.
      operationId: list_events
      parameters:
        - name: X-Pubkey
          in: header
          description: >-
            Integrator's ECDSA public key (P-256 curve, compressed SEC1 format).
            Example:
            0x038fedef7c12f93bbf342ad8943b7a825a3b41f61c9dc118b2c718efebabbf62fd
          required: true
          schema:
            type: string
        - name: X-Timestamp
          in: header
          description: >-
            Unix timestamp in seconds (UTC). Must be within tolerance window (1
            minute) to prevent replay attacks. Example: 1760375826
          required: true
          schema:
            type: string
        - name: X-Signature
          in: header
          description: >-
            ECDSA signature (DER-encoded, hex with 0x prefix). Signs the
            message: {timestamp}{METHOD}{path_and_query}{json_body}. Example:
            0x3045022100...
          required: true
          schema:
            type: string
        - name: accountId
          in: query
          description: Filter by account ID.
          required: false
          schema:
            allOf:
              - $ref: '#/components/schemas/Uuid'
            nullable: true
        - name: userId
          in: query
          description: Filter by user ID.
          required: false
          schema:
            allOf:
              - $ref: '#/components/schemas/Uuid'
            nullable: true
        - name: transactionId
          in: query
          description: Filter by transaction ID.
          required: false
          schema:
            allOf:
              - $ref: '#/components/schemas/Uuid'
            nullable: true
        - name: eventType
          in: query
          description: >-
            Filter by a lifecycle event type. `webhook.test` is not a lifecycle
            event.
          required: false
          schema:
            type: string
            nullable: true
        - name: createdAfter
          in: query
          description: Exclusive lower bound on database creation time.
          required: false
          schema:
            type: string
            format: date-time
            nullable: true
        - name: createdBefore
          in: query
          description: Exclusive upper bound on database creation time.
          required: false
          schema:
            type: string
            format: date-time
            nullable: true
        - name: cursor
          in: query
          description: Opaque page cursor. Keep filters unchanged while paging.
          required: false
          schema:
            type: string
            nullable: true
        - name: limit
          in: query
          description: Page size from 1 to 250. Defaults to 100.
          required: false
          schema:
            type: integer
            format: int64
            nullable: true
      responses:
        '200':
          description: Event history
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListEventsResponse'
        '400':
          description: Bad request - Invalid filter, cursor or limit
        '401':
          description: Unauthorized - Invalid credential or signature
        '500':
          description: Internal server error
      security:
        - integrator_auth: []
components:
  schemas:
    Uuid:
      type: string
      format: uuid
      description: A UUID string
      example: 550e8400-e29b-41d4-a716-446655440000
    ListEventsResponse:
      type: object
      description: One page of events with an opaque cursor for the next page, if any.
      required:
        - events
      properties:
        events:
          type: array
          items:
            $ref: '#/components/schemas/EventHistoryItem'
        nextCursor:
          type: string
          nullable: true
    EventHistoryItem:
      allOf:
        - $ref: '#/components/schemas/WebhookLifecycleEventPayload'
        - type: object
          required:
            - createdAt
          properties:
            createdAt:
              type: string
              format: date-time
      description: Canonical lifecycle event payload plus its database creation time.
    WebhookLifecycleEventPayload:
      type: object
      description: >-
        Stable public webhook payload shared by customer and transaction
        lifecycle events.
      required:
        - id
        - eventType
        - occurredAt
        - livemode
        - payloadVersion
        - integratorId
      properties:
        id:
          $ref: '#/components/schemas/Uuid'
        eventType:
          $ref: '#/components/schemas/WebhookEventType'
        occurredAt:
          type: string
          format: date-time
        livemode:
          type: boolean
        payloadVersion:
          type: integer
          format: int32
        integratorId:
          $ref: '#/components/schemas/Uuid'
        accountId:
          allOf:
            - $ref: '#/components/schemas/Uuid'
          nullable: true
        userId:
          allOf:
            - $ref: '#/components/schemas/Uuid'
          nullable: true
        entityId:
          allOf:
            - $ref: '#/components/schemas/Uuid'
          nullable: true
        beneficiaryId:
          allOf:
            - $ref: '#/components/schemas/Uuid'
          nullable: true
        transactionId:
          allOf:
            - $ref: '#/components/schemas/Uuid'
          nullable: true
        provider:
          allOf:
            - $ref: '#/components/schemas/WebhookEventProvider'
          nullable: true
        providerEventId:
          type: string
          nullable: true
        data: {}
    WebhookEventType:
      type: string
      description: Public outbound webhook event names. Stored as TEXT in Postgres.
      enum:
        - webhook.test
        - customer.created
        - customer.updated
        - customer.under_review
        - customer.awaiting_associated_person_information
        - customer.resubmission_requested
        - customer.active
        - customer.rejected
        - customer.deleted
        - transaction.created
        - transaction.withdrawal_initiated
        - transaction.waiting_for_funds
        - transaction.payment_in_review
        - transaction.funds_in_transfer
        - transaction.funds_received
        - transaction.processing
        - transaction.completed
        - transaction.simulation_failed
        - transaction.reverted
      example: customer.created
    WebhookEventProvider:
      type: string
      description: Provider/source that caused a public lifecycle webhook event.
      enum:
        - byzantine
        - sumsub
        - bridge
        - onchain
      example: byzantine
  securitySchemes:
    integrator_auth:
      type: apiKey
      in: header
      name: X-Pubkey, X-Timestamp, X-Signature

````