Webhook Events

Read-only audit log of every webhook delivery the system has queued or attempted on your behalf. Useful for retrospectively confirming whether a missed event was sent and what HTTP status your endpoint returned.

There is no merchant self-service replay endpoint. Use the manual replay procedure for stored, failed deliveries.

All examples below assume Authorization: Bearer mer_live_… is set; see Authentication.

List webhook events

GET /api/v1/merchant/webhook-events

Cursor-paginated.

Query parameters

Name	Type	Notes
`cursor`	string	Opaque, from previous `next_cursor`.
`limit`	int	1–200, default 50.
`status`	enum	`pending` / `delivered` / `failed`. Omit for all. Unknown values return `400 MERCHANT_INVALID_STATUS`. (`sending` is a transient claim window — not a filterable value.)
`order_id`	uuid	Restrict to events for one purchase. None for `balance.deposited`.

Example

curl --compressed "https://merchant-api.tradeon.market/api/v1/merchant/webhook-events?status=failed&limit=10" \
  -H "Authorization: Bearer mer_live_…"

{
  "events": [
    {
      "id": "11111111-2222-3333-4444-555555555555",
      "event_type": "purchase.completed",
      "order_id": "1a2b3c4d-5e6f-7080-91a2-b3c4d5e6f708",
      "delivery_status": "failed",
      "delivery_attempts": 4,
      "last_response_code": 500,
      "created_at": "2026-05-05T16:02:14.000Z",
      "delivered_at": null
    }
  ],
  "next_cursor": null
}

Fields

Field	Type	Notes
`id`	uuid	The `event_id` carried in the delivery and the body.
`event_type`	string	One of the eight types in the event catalogue. Accept new types for forward compatibility.
`order_id`	uuid \| null	Purchase ID; `null` for `balance.deposited`.
`delivery_status`	enum	`pending` (queued, awaiting next attempt) / `delivered` / `failed`. May transiently surface as `sending` while an attempt is in progress; not accepted by the `?status=` filter.
`delivery_attempts`	int	Attempt counter, including any manual replays.
`last_response_code`	int \| null	Your endpoint’s most recent HTTP status, or `0` for transport errors and pre-flight SSRF rejections.
`created_at`	ISO 8601
`delivered_at`	ISO 8601 \| null	Timestamp of the successful 2xx, when applicable.

Health monitoring

This is a delivery log of stored events, not a complete ledger of every business transition. An absent row does not prove the purchase never changed. Reconcile with purchase history and balance.

A simple production signal: alert when pending events older than ~10 minutes exceed a threshold, or when failed deliveries grow over a window. We do not push this data — poll on the cadence that fits your ops setup.