Events
Read-only webhook delivery log.
GET /v1/events
List webhook deliveries
Read-only view of deliveries (one row per event per webhook), for debugging and reconciliation. Delivered/failed rows are purged after WEBHOOK_EVENT_RETENTION_DAYS (default 30).
- Authentication
- Merchant API key
- Effect
- Read-only.
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
limit | integer | no | Page size (1–100). · ≥ 1, ≤ 100, default 20 |
starting_after | string | no | Object ID; return objects after it (ascending ID order). · 26 chars |
type | EventType | no | Filter by event type. |
webhook | string | no | Filter by webhook ID. · 26 chars |
status | "pending" | "delivered" | "failed" | no | Filter by delivery status. |
Responses
| Status | Meaning | Body / error codes |
|---|---|---|
| 200 | Success. | object |
| 400 | Invalid request. | invalid_query_param |
| 401 | Missing or invalid API key. | authentication_error |
| 429 | Rate limited; honor retry-after. | rate_limit_exceeded too_many_auth_failures |
| 500 | Server error. | api_error |
Example response
{
"object": "list",
"url": "string",
"has_more": false,
"data": [
{
"object": "webhook_event",
"id": "01JB9XK3M2R7TQ8N4V6Y0ZPA1C",
"merchant_id": "01JB9XK3M2R7TQ8N4V6Y0ZPA1C",
"webhook_id": "01JB9XK3M2R7TQ8N4V6Y0ZPA1C",
"event_type": "customer.created",
"payload": {},
"status": "pending",
"attempts": 1,
"last_attempt_at": "2026-10-25T18:00:00.000Z",
"next_retry_at": "2026-10-25T18:00:00.000Z",
"created_at": "2026-10-25T18:00:00.000Z"
}
]
}GET /v1/events/:id
Retrieve a delivery
Includes payload, attempts and next_retry_at.
- Authentication
- Merchant API key
- Effect
- Read-only.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | yes | Object ID (ULID). · 26 chars |
Responses
| Status | Meaning | Body / error codes |
|---|---|---|
| 200 | Success. | WebhookEvent |
| 401 | Missing or invalid API key. | authentication_error |
| 404 | Not found, or not yours. | resource_missing |
| 429 | Rate limited; honor retry-after. | rate_limit_exceeded too_many_auth_failures |
| 500 | Server error. | api_error |
Example response
{
"object": "webhook_event",
"id": "01JB9XK3M2R7TQ8N4V6Y0ZPA1C",
"merchant_id": "01JB9XK3M2R7TQ8N4V6Y0ZPA1C",
"webhook_id": "01JB9XK3M2R7TQ8N4V6Y0ZPA1C",
"event_type": "customer.created",
"payload": {},
"status": "pending",
"attempts": 1,
"last_attempt_at": "2026-10-25T18:00:00.000Z",
"next_retry_at": "2026-10-25T18:00:00.000Z",
"created_at": "2026-10-25T18:00:00.000Z"
}