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

# List webhook events

> Returns a cursor-paginated list of events written for your organization, oldest first unless `order=desc`. Filter by `type`, by `endpoint_id` (events attempted to that endpoint, each carrying its latest `delivery` to it) by `resource_id`, or by a `since`/`until` window.



## OpenAPI

````yaml /openapi.json get /v1/webhooks/events
openapi: 3.1.0
info:
  title: Endstate API
  version: 0.1.0
  description: Endstate developer API for chip verification and ownership workflows.
servers:
  - url: https://api2.endstate.io
    description: Production
  - url: https://api-staging.endstate.io
    description: Staging
security: []
paths:
  /v1/webhooks/events:
    get:
      tags:
        - Webhooks
      summary: List webhook events
      description: >-
        Returns a cursor-paginated list of events written for your organization,
        oldest first unless `order=desc`. Filter by `type`, by `endpoint_id`
        (events attempted to that endpoint, each carrying its latest `delivery`
        to it) by `resource_id`, or by a `since`/`until` window.
      operationId: listWebhookEvents
      parameters:
        - schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 50
            description: Maximum number of records to return. Defaults to 50; maximum 100.
          required: false
          name: limit
          in: query
        - schema:
            type: string
            minLength: 1
            description: Opaque cursor from the previous page.
          required: false
          name: cursor
          in: query
        - schema:
            type: string
            minLength: 1
            example: example.updated
          required: false
          name: type
          in: query
        - schema:
            type: string
            format: uuid
            description: Only events with at least one delivery attempt to this endpoint.
          required: false
          name: endpoint_id
          in: query
        - schema:
            type: string
            enum:
              - asc
              - desc
            default: asc
            description: Oldest first (`asc`, the default) or newest first (`desc`).
          required: false
          name: order
          in: query
        - schema:
            type: string
            format: date-time
            description: Only events created at or after this time.
            example: '2026-09-22T00:00:00Z'
          required: false
          name: since
          in: query
        - schema:
            type: string
            format: date-time
            description: Only events created at or before this time.
            example: '2026-09-23T00:00:00Z'
          required: false
          name: until
          in: query
        - schema:
            type: string
            minLength: 1
            maxLength: 200
            description: >-
              Only events about this resource, matched exactly against
              `resource.id`.
          required: false
          name: resource_id
          in: query
        - schema:
            type: string
            enum:
              - succeeded
              - failed
              - pending
            description: >-
              With `endpoint_id`: only events whose latest attempt to that
              endpoint has this status. `pending` is queued, in flight or
              waiting to retry; `succeeded` and `failed` are how the latest
              attempt ended. The same rule classifies each row's
              `delivery.status` and the endpoint's health counts.
          required: false
          name: delivery_status
          in: query
      responses:
        '200':
          description: A page of webhook events.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookEventsListResponse'
              example:
                webhook_events:
                  - id: 3f1c9a2b-7d4e-4f10-9a8b-2c6d5e4f3a21
                    type: example.updated
                    audience: brand
                    api_version: '2026-09-01'
                    resource:
                      type: example
                      id: 6b1e2a3c-4d5e-4f60-8172-839405162738
                      revision: 1
                    created_at: '2026-09-22T12:00:00.000Z'
                pagination:
                  limit: 50
                  has_more: false
                  next_cursor: null
        '400':
          description: >-
            The request was malformed or failed validation.


            | Error code | When |

            | --- | --- |

            | `validation.failed` | The request failed schema validation. See
            `error.details` for per-field issues. |
          x-error-codes:
            - validation.failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                validation.failed:
                  summary: >-
                    The request failed schema validation. See `error.details`
                    for per-field issues.
                  value:
                    error:
                      code: validation.failed
                      message: >-
                        The request failed schema validation. See
                        `error.details` for per-field issues.
                      request_id: req_8e1a7f50-90ab-4cde-f012-3456789abcde
                      doc_url: https://docs.endstate.io/errors/validation-failed
        '401':
          description: |-
            Authentication failed.

            | Error code | When |
            | --- | --- |
            | `auth.unauthorized` | Credential is missing or malformed. |
          x-error-codes:
            - auth.unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                auth.unauthorized:
                  summary: Credential is missing or malformed.
                  value:
                    error:
                      code: auth.unauthorized
                      message: Credential is missing or malformed.
                      request_id: req_8e1a7f50-90ab-4cde-f012-3456789abcde
                      doc_url: https://docs.endstate.io/errors/auth-unauthorized
        '403':
          description: >-
            Authenticated, but not permitted.


            | Error code | When |

            | --- | --- |

            | `auth.forbidden` | Credential is valid but does not have access to
            the requested resource or action. |
          x-error-codes:
            - auth.forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                auth.forbidden:
                  summary: >-
                    Credential is valid but does not have access to the
                    requested resource or action.
                  value:
                    error:
                      code: auth.forbidden
                      message: >-
                        Credential is valid but does not have access to the
                        requested resource or action.
                      request_id: req_8e1a7f50-90ab-4cde-f012-3456789abcde
                      doc_url: https://docs.endstate.io/errors/auth-forbidden
        '429':
          description: |-
            Too many requests.

            | Error code | When |
            | --- | --- |
            | `rate_limit.exceeded` | Per-key rate limit exceeded. |
          x-error-codes:
            - rate_limit.exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                rate_limit.exceeded:
                  summary: Per-key rate limit exceeded.
                  value:
                    error:
                      code: rate_limit.exceeded
                      message: Per-key rate limit exceeded.
                      request_id: req_8e1a7f50-90ab-4cde-f012-3456789abcde
                      doc_url: https://docs.endstate.io/errors/rate-limit-exceeded
        '500':
          description: >-
            Something went wrong on our end.


            | Error code | When |

            | --- | --- |

            | `internal.error` | An unexpected server error occurred. Retry with
            exponential backoff and include `request_id` in any support request.
            |
          x-error-codes:
            - internal.error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                internal.error:
                  summary: >-
                    An unexpected server error occurred. Retry with exponential
                    backoff and include `request_id` in any support request.
                  value:
                    error:
                      code: internal.error
                      message: >-
                        An unexpected server error occurred. Retry with
                        exponential backoff and include `request_id` in any
                        support request.
                      request_id: req_8e1a7f50-90ab-4cde-f012-3456789abcde
                      doc_url: https://docs.endstate.io/errors/internal-error
      security:
        - ApiKeyBearer: []
components:
  schemas:
    WebhookEventsListResponse:
      type: object
      properties:
        webhook_events:
          type: array
          items:
            $ref: '#/components/schemas/WebhookEventListItem'
        pagination:
          $ref: '#/components/schemas/CursorPagination'
      required:
        - webhook_events
        - pagination
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              anyOf:
                - $ref: '#/components/schemas/ErrorCode'
                - type: string
              description: >-
                Stable, namespaced error code. The `ErrorCode` catalogue lists
                every code defined today; handle an unrecognized value as a
                generic failure rather than throwing, since codes are added over
                time.
              example: chip.not_found
            message:
              type: string
              description: >-
                Human-readable description, for logs and debugging. Wording may
                change without notice - never parse or match against it.
              example: Chip not found
            request_id:
              type: string
              description: >-
                Identifier for this request, matching the `X-Request-Id`
                response header. Log it and include it in any support request.
              example: req_8e1a7f50-90ab-4cde-f012-3456789abcde
            doc_url:
              type: string
              description: Documentation page for this error code.
              example: https://docs.endstate.io/errors/chip-not-found
            details:
              $ref: '#/components/schemas/ValidationErrorDetails'
          required:
            - code
            - message
            - request_id
            - doc_url
      required:
        - error
      description: >-
        Every error response, regardless of endpoint or HTTP status, uses this
        envelope.
    WebhookEventListItem:
      allOf:
        - $ref: '#/components/schemas/WebhookEvent'
        - type: object
          properties:
            delivery:
              $ref: '#/components/schemas/WebhookDeliverySummary'
    CursorPagination:
      type: object
      properties:
        limit:
          type: integer
          exclusiveMinimum: 0
          description: Maximum number of records returned.
          example: 50
        has_more:
          type: boolean
          description: Whether another page is available. Pass `next_cursor` to fetch it.
          example: false
        next_cursor:
          type:
            - string
            - 'null'
          description: Opaque cursor for the next page. Null when there is no next page.
          example: >-
            eyJjcmVhdGVkX2F0IjoiMjAyNi0wNS0xNlQxMjowMDowMC4wMDBaIiwiaWQiOiIzMzMzMzMzMy0zMzMzLTMzMzMtMzMzMy0zMzMzMzMzMzMzMzMifQ
      required:
        - limit
        - has_more
        - next_cursor
    ErrorCode:
      type: string
      enum:
        - environment.conflict
        - environment.invalid_configuration
        - organization.changed
        - validation.failed
        - auth.unauthorized
        - auth.forbidden
        - session_token.invalid_or_expired
        - session_token.wrong_chip
        - wallet_session.invalid_or_expired
        - not_found.resource
        - rate_limit.exceeded
        - chip.not_found
        - chip.invalid_e_value
        - chip.already_scanned
        - quota.exceeded
        - chip.not_a_test_chip
        - unit.not_found
        - unit.already_exists
        - unit.not_minted
        - collection.not_found
        - collection.already_exists
        - collection.not_active
        - collection_backfill.blocked
        - organization.not_found
        - chip.already_paired
        - chip.key_unusable
        - chip.mac_required
        - chip.bulk_mixed_collections
        - chip.bulk_pending
        - unit.issuance_pending
        - claim.owner_unknown
        - claim.already_to_recipient
        - claim.in_progress
        - claim.not_found
        - chip_replacement.locked
        - chip_replacement.in_progress
        - chip_replacement.not_found
        - transfer.owner_unknown
        - transfer.already_to_recipient
        - transfer.in_progress
        - transfer.not_found
        - submission.not_executable
        - vault.not_found
        - vault.already_exists
        - vault.provisioning_failed
        - vault.not_permitted
        - vault.unavailable
        - vault.challenge_invalid
        - vault.address_in_use
        - vault.key_conflict
        - vault.signer_unauthorized
        - vault_connection.not_found
        - vault_connection.not_active
        - vault_connection.already_exists
        - vault_connection.conflict
        - idempotency.key_conflict
        - idempotency.in_progress
        - internal.error
        - webhook_endpoint.not_found
        - webhook_endpoint.deleted
        - webhook_endpoint.limit_reached
        - webhook_endpoint.url_refused
        - webhook_endpoint.signing_unavailable
        - webhook_event_type.unknown
        - webhook_event.not_found
        - webhook_endpoint.disabled
        - webhook_delivery.in_progress
        - webhook_endpoint.not_subscribed
      description: >-
        Stable, namespaced error code in `<resource>.<reason>` form. Branch on
        this rather than on `message` or the HTTP status. This is the catalogue
        as of this spec revision, not a closed set - see
        `ErrorResponse.error.code`.
      example: chip.not_found
    ValidationErrorDetails:
      type: object
      properties:
        formErrors:
          type: array
          items:
            type: string
          description: Issues that apply to the request as a whole rather than one field.
          example: []
        fieldErrors:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
          description: Validation issues keyed by the field that failed.
          example:
            name:
              - Required
      required:
        - formErrors
        - fieldErrors
      description: Per-field validation detail. Present only on `validation.failed`.
    WebhookEvent:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Event id; also the `webhook-id` header on every delivery.
          example: 3f1c9a2b-7d4e-4f10-9a8b-2c6d5e4f3a21
        type:
          type: string
          example: example.updated
        audience:
          type: string
          description: Which view of the resource the payload carries.
          example: brand
        api_version:
          type: string
          example: '2026-09-01'
        resource:
          type: object
          properties:
            type:
              type: string
              example: warranty
            id:
              type: string
              example: 6b1e2a3c-4d5e-4f60-8172-839405162738
            revision:
              type: integer
              example: 1
          required:
            - type
            - id
            - revision
        created_at:
          type: string
          format: date-time
      required:
        - id
        - type
        - audience
        - api_version
        - resource
        - created_at
    WebhookDeliverySummary:
      type: object
      properties:
        status:
          type: string
          enum:
            - pending
            - succeeded
            - failed
        attempts:
          type: integer
          description: Attempts made to the endpoint so far, including the latest.
          example: 2
        response_status_code:
          type:
            - integer
            - 'null'
          example: 500
        error:
          type:
            - string
            - 'null'
        last_attempt_at:
          type:
            - string
            - 'null'
          format: date-time
          description: When the last completed attempt finished; null before any completes.
        next_attempt_at:
          type:
            - string
            - 'null'
          format: date-time
          description: When the pending attempt is due; null when none is scheduled.
      required:
        - status
        - attempts
        - response_status_code
        - error
        - last_attempt_at
        - next_attempt_at
      description: >-
        How deliveries to the endpoint named by `endpoint_id` stand. Present
        only on a list filtered by endpoint.
  securitySchemes:
    ApiKeyBearer:
      type: http
      scheme: bearer
      bearerFormat: end_sk
      description: >-
        Use `Authorization: Bearer end_sk_*` for partner API keys (e.g.
        `end_sk_AbCd_example_api_key`).

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.