列出 Webhook 事件 | ToAPIs Documentation

GET

/api/v1/webhook/events

国内用户请注意: 中国大陆用户请使用 https://api.toapis.cn 作为接口地址 (Base URL). 文档示例中的 https://api.toapis.com 请替换为 https://api.toapis.cn.

使用说明

查询 Webhook 回调的投递记录, 用于确认是否送达和排查失败原因. 省略 api_key_id 时返回名下全部事件. 提供时校验是否为自有普通模型 Key (已软删除的 Key 也可用). 默认查询近 24 小时, from/to 必须成对提供, 区间最长 31 天. limit 默认 50, 最大 100, 按内部 ID 倒序分页.

游标绑定账户和筛选条件, 翻页时保持筛选不变. 后续翻页时省略 from/to, 会沿用第一页请求确定的时间范围, 而不是按翻页时刻重新计算.

鉴权

Authorizationstring请求头必填

使用系统访问令牌, 格式为 Bearer YOUR_SYSTEM_ACCESS_TOKEN, 只能访问当前账号自己的数据. 不接受模型 Key, 无需 X-User-Id, 也没有管理端或团队旁路.

请求参数

api_key_idinteger查询

自有普通模型 Key 的正整数 ID (不是 sk- 密钥或系统访问令牌). 查询参数中必须是正整数, 不接受字符串, 省略或 null.

task_idstring查询

平台任务 ID.

statusstring查询

投递状态. pending/delivering/delivered/dead/cancelled.

fromstring查询

带时区 RFC 3339 时间, from/to 成对.

tostring查询

带时区 RFC 3339 时间, from/to 成对.

limitinteger查询

每页条数, 默认 50, 最大 100.

cursorstring查询

上一页返回的游标.

参数无效返回 400; 筛选的 Key 不存在或属于他人统一返回 404; 触发限流返回 429.

请求示例

curl --request GET \
  --url 'https://api.toapis.com/api/v1/webhook/events' \
  --header 'Authorization: Bearer YOUR_SYSTEM_ACCESS_TOKEN'

响应示例

{
  "code": 0,
  "message": "",
  "data": {
    "items": [
      {
        "event_id": "evt_example",
        "api_key_id": 123,
        "task_id": "example-task",
        "type": "generation.completed",
        "status": "delivered",
        "attempts": 1,
        "reason": "delivered",
        "last_http_status": 200,
        "created_at": "2026-11-13T00:00:00Z",
        "next_attempt_at": null,
        "delivered_at": "2026-11-13T00:00:01Z",
        "expires_at": "2026-11-14T12:00:00Z"
      }
    ],
    "has_more": false,
    "next_cursor": null,
    "meta": {
      "scope": "self",
      "from": "2026-11-12T01:00:00Z",
      "to": "2026-11-13T01:00:00Z",
      "consistency": "eventual"
    }
  }
}

首次接入顺序与签名验签说明见查询 Webhook 配置.