Webhook 事件歷史

查詢當前賬號的 webhook 投遞歷史。常用場景：

• 排查"為什麼我的 webhook 沒收到"
• 監控 dead_letter 狀態的死信
• 與本地業務記錄對賬

端點

項	值
Method	POST
Path	/api/v1/openapi/webhook_events/list
鑑權	HMAC
冪等鍵	不需要

請求欄位

欄位	型別	必填	說明
event_type	string	否	過濾事件型別，如 card.opened
status	int	否	過濾投遞狀態（見下表）
page	int	否	預設 1
page_size	int	否	預設 20，最大 100

投遞狀態

status	status_desc	含義
0	pending	等待首次投遞
1	delivered	投遞成功
2	failed_retry	失敗但仍在重試
3	dead_letter	已死信，不再重試
4	skipped	跳過（如 webhook URL 未配置）

請求示例

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

響應欄位

data.list[] 中每項：

欄位	型別	說明
event_id	string	evt_<uuid>（與 Webhook-Id 頭去字首後一致）
event_type	string	事件型別
status	int	見上表
status_desc	string	英文描述
attempt_count	int	已嘗試次數
next_attempt_at	string nullable	下次重試時間（RFC3339）
last_error	string	最近一次失敗原因
last_response_status	int	最近一次 HTTP 狀態碼（0 = 網路層失敗）
delivered_at	string nullable	投遞成功時間
created_at	string	事件建立時間

響應示例

{
  "code": 200,
  "message": "成功",
  "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
  }
}

典型錯誤

HTTP	message_key	說明
401	openapi_invalid_credentials	鑑權失敗
500	openapi_list_webhook_events_failed	服務端異常

排查 Webhook 投遞問題

場景 1：本地一直沒收到 webhook

# 看是不是根本沒投遞
{ "status": 0 }    # 仍 pending → 系統側延遲，等幾秒再看
{ "status": 4 }    # skipped → 你 webhook URL 沒配 / 已停用

# 或失敗重試中
{ "status": 2 }    # 看 last_error / last_response_status 判斷

場景 2：懷疑漏事件

# 列你的 card_id 相關事件
{ "event_type": "card.opened", "page_size": 100 }
# 與本地接收記錄對賬

場景 3：確認死信

{ "status": 3 }
# 死信通常是：URL 永久 4xx / 永久 timeout / DNS 失敗
# 修好接收器後，聯絡支援手動重投或忽略