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 失败
# 修好接收器后，联系支持手动重投或忽略