Webhook Events History

Query the webhook delivery history for the current account. Common uses:

• Diagnose "why didn't I receive a webhook"
• Monitor dead-letter status
• Reconcile against your local records

Endpoint

Item	Value
Method	POST
Path	/api/v1/openapi/webhook_events/list
Auth	HMAC
Idempotency	Not required

Request Fields

Field	Type	Required	Description
event_type	string	No	Filter by event type, e.g. card.opened
status	int	No	Filter by delivery status (see table)
page	int	No	Default 1
page_size	int	No	Default 20, max 100

Delivery Status

status	status_desc	Meaning
0	pending	Awaiting first delivery
1	delivered	Delivered
2	failed_retry	Failed but still retrying
3	dead_letter	Dead-lettered, no more retries
4	skipped	Skipped (e.g. webhook URL not set)

Example Request

{ "event_type": "card.opened", "status": 1, "page": 1, "page_size": 20 }

Response Fields

Each item in data.list[]:

Field	Type	Description
event_id	string	evt_<uuid> (matches Webhook-Id header without prefix)
event_type	string	Event type
status	int	See table
status_desc	string	English description
attempt_count	int	Attempts so far
next_attempt_at	string nullable	Next retry time (RFC3339)
last_error	string	Most recent failure reason
last_response_status	int	Most recent HTTP status (0 = network failure)
delivered_at	string nullable	Delivery time on success
created_at	string	Event creation time

Example Response

{
  "code": 200,
  "message": "OK",
  "data": {
    "list": [
      {
        "event_id": "evt_550e8400-e29b-41d4-a716-446655440000",
        "event_type": "card.opened",
        "status": 1,
        "status_desc": "delivered",
        "attempt_count": 1,
        "next_attempt_at": null,
        "last_error": "",
        "last_response_status": 200,
        "delivered_at": "2026-04-29T11:00:13Z",
        "created_at": "2026-04-29T11:00:12Z"
      }
    ],
    "total": 12,
    "page": 1,
    "page_size": 20,
    "total_pages": 1,
    "has_next": false,
    "has_prev": false
  }
}

Common Errors

HTTP	message_key	Description
401	openapi_invalid_credentials	Auth failure
500	openapi_list_webhook_events_failed	Server error

Diagnosing Webhook Issues

Scenario 1: Never received a webhook

# Was it ever queued?
{ "status": 0 }    # still pending → system delay, wait a few seconds
{ "status": 4 }    # skipped → URL not set / disabled

# Or in retry loop
{ "status": 2 }    # check last_error / last_response_status

Scenario 2: Suspect missing events

# List all events for the time range
{ "event_type": "card.opened", "page_size": 100 }
# Reconcile with your local receiver records

Scenario 3: Confirm dead-letter

{ "status": 3 }
# Dead-letters typically come from: permanent 4xx / permanent timeout / DNS failure
# After fixing your receiver, contact support to manually re-deliver or ignore