查询 Webhook 配置 | ToAPIs Documentation

GET

/api/v1/webhook

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

使用说明

读取指定 Key 的 Webhook 配置, 包括回调地址, 启用状态和最近投递健康状况. 每个模型 Key 对应一份 Webhook 配置, 已软删除的 Key 也可以读取. 本接口只返回 secret_configured 表示是否已配置密钥, 不会返回密钥原文. 未设置的地址和时间返回 null. 管理接口时间统一为 RFC 3339 格式.

健康信息读取失败时 health.state=unknown, 不代表配置写入失败.

鉴权

Authorizationstring请求头必填

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

请求参数

api_key_idinteger查询必填

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

api_key_id 缺失或不是正整数返回 400; 目标 Key 不存在或属于他人统一返回 404; 触发限流返回 429. mode=off 只限制写操作, 不影响本接口读取.

请求示例

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

响应示例

{
  "code": 0,
  "message": "",
  "data": {
    "api_key_id": 123,
    "enabled": false,
    "url": null,
    "secret_configured": false,
    "previous_secret_expires_at": null,
    "updated_at": null,
    "mode": "enforce",
    "health": {
      "state": "disabled",
      "failure_kind": null,
      "consecutive_failures": 0,
      "suspended_until": null,
      "last_http_status": null,
      "last_failure_at": null
    }
  }
}

首次接入

调用 POST /api/v1/webhook/rotate-secret 生成签名密钥. secret 只在本次响应中返回一次, 立即保存到接收端; 初始化不会自动启用回调.
在接收端按下方的签名验签规则完成配置.
调用 PATCH /api/v1/webhook 设置回调地址并传入 enabled=true. 首次启用或更换地址会创建 endpoint.test 验证事件, 响应返回 verification_event_id.
调用 POST /api/v1/webhook/test 发送测试事件, 或用 GET /api/v1/webhook/events/{event_id} 查询验证与投递结果.

签名验签

每个回调请求携带三个请求头: X-ToAPIs-Webhook-Id 为事件 ID, X-ToAPIs-Webhook-Timestamp 为 Unix 秒时间戳, X-ToAPIs-Webhook-Signature 为签名.

验签时将事件 ID, 时间戳和原始请求体用 . 拼接成 event_id.timestamp.raw_body, 用保存的 secret 计算 HMAC-SHA256, 与签名头中 v1= 后的十六进制摘要比较. 必须对原始请求体字节验签, 不要解析后重新序列化. 密钥轮换过渡期内签名头可能包含多个逗号分隔的 v1= 值, 任一匹配即有效.

接收端按事件 ID 去重. 回调 payload 和签名时间戳使用 Unix 秒, 管理接口时间使用 RFC 3339.