Webhook Events¶

Endpoint	Method	Scope	Token Tier	Description
`/api/v1/webhook-events/`	GET	`webhooks:read`	Both	List the webhook events delivered to you
`/api/v1/webhook-events/<msg_id>/`	GET	`webhooks:read`	Both	Retrieve one delivered event, including body

Try it out

Explore parameters, schemas, and live requests in the Swagger UI.

These endpoints let you read back the webhook events Beyond has already sent to your endpoint — useful for reconciling events you may have missed while your receiver was down. They report what was delivered and how it landed (delivery status, HTTP response code, and any error), not the raw HTTP retries. For the event catalog and payload shapes, see Webhooks.

The msg_id is the same stable id Beyond sends in the webhook-id header of each delivery (the value you dedupe on).

Token scope determines visibility

An application-level token sees every event delivered to the app's webhook endpoint. A user-scoped token sees only the events belonging to the user it is bound to. Visibility is derived from your token — there is no query parameter to widen it.

List Webhook Events¶

Returns a paginated list of the events delivered to your application, newest first. Supports pagination.

Filtering:
- filter[event-type]=<type> — only events of one type (e.g. listing.refreshed).
- filter[status]=<status> — only events in one delivery status: pending, delivered, failed, or exhausted. Any other value returns 400.
- filter[created-after]=<timestamp> — only events created at or after an ISO 8601 timestamp (e.g. 2026-07-13T19:00:00Z).
- filter[created-before]=<timestamp> — only events created at or before an ISO 8601 timestamp. Combine with created-after to bound a window.
Including the body: include-body=true inlines each event's full body (as a nested JSON object) into every list item, so you can reconcile and reprocess a range of events without a follow-up request per event. It is off by default to keep the list light.

GET /api/v1/webhook-events/?filter[status]=failed&filter[created-after]=2026-07-13T19:00:00Z&include-body=true&page[size]=50

By default each resource carries the delivery metadata and outcome, but not the body — either pass include-body=true above, or fetch a single event.

Response¶

{
  "data": [
    {
      "type": "webhook-events",
      "id": "msg_2h9pXbFqR7Jk",
      "attributes": {
        "event-type": "listing.refreshed",
        "status": "delivered",
        "content-type": "application/vnd.api+json",
        "attempts": 1,
        "last-status-code": 200,
        "last-error": null,
        "created-at": "2026-08-01T10:15:00Z",
        "delivered-at": "2026-08-01T10:15:02Z",
        "failed-at": null
      }
    }
  ],
  "meta": {
    "pagination": {"page": 1, "pages": 1, "count": 1}
  }
}

Attribute	Description
`event-type`	The event that was delivered.
`status`	`pending`, `delivered`, `failed`, or `exhausted`.
`content-type`	Content-Type of the delivery.
`attempts`	Number of delivery attempts made.
`last-status-code`	HTTP status of the last delivery attempt (if any).
`last-error`	Error from the last failed attempt (if any).
`created-at`	When Beyond accepted the event.
`delivered-at`	When the event was delivered with a 2xx (if it was).
`failed-at`	When the event reached a terminal failure (if it did).

Delivery status¶

Value	Meaning
`pending`	Accepted; delivery is still in flight or being retried.
`delivered`	Your endpoint returned a 2xx.
`failed`	Your endpoint returned a non-retryable response; the event was dropped.
`exhausted`	Retryable failures exhausted all attempts; the event was not delivered.

Retrieve a Webhook Event¶

Returns a single delivered event, including the body that was sent — the JSON:API document your endpoint received, returned as a nested JSON object you can traverse directly (not an escaped string). It also adds url, the endpoint this event was delivered to (omitted from the list, where it is identical on every row). The event is returned only when it falls within your token's scope; a msg_id belonging to another partner (or, for a user-scoped token, another user) returns 404 Not Found.

GET /api/v1/webhook-events/msg_01H.../

Response¶

The detail resource carries every list attribute plus url and body:

{
  "data": {
    "type": "webhook-events",
    "id": "msg_2h9pXbFqR7Jk",
    "attributes": {
      "event-type": "listing.refreshed",
      "status": "delivered",
      "content-type": "application/vnd.api+json",
      "attempts": 1,
      "last-status-code": 200,
      "last-error": null,
      "created-at": "2026-08-01T10:15:00Z",
      "delivered-at": "2026-08-01T10:15:02Z",
      "failed-at": null,
      "url": "https://partner.example.com/webhooks/beyond",
      "body": {
        "data": {
          "type": "listing-refreshed-events",
          "id": "msg_2h9pXbFqR7Jk",
          "attributes": {"...": "the document your endpoint received"}
        }
      }
    }
  }
}

Use cases¶

Gap recovery. After receiver downtime, list with filter[created-after] set to the outage start and include-body=true, then feed each body through the same handler your live endpoint uses.
Delivery monitoring. Poll filter[status]=exhausted (and failed) to detect events that never reached you, with last-status-code / last-error explaining why.
Dedupe audit. Cross-check the webhook-id values you processed against the ids listed here to confirm nothing was silently dropped.

Errors¶

Status	Cause
`400`	Unknown `filter[status]` value, or a malformed timestamp filter.
`401`	Missing or invalid bearer token.
`403`	Token does not have the `webhooks:read` scope.
`404`	`msg_id` not found within your token's scope.
`429`	Rate limit exceeded. See Rate Limiting.