更新 Webhook 配置 | ToAPIs Documentation

PATCH

/api/v1/webhook

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

使用说明

设置或修改指定 Key 的回调地址和启用状态, enabled 和 url 至少提供一个, 省略的字段保持原值. 启用前必须先配置密钥和公网 HTTPS 回调地址. 单独 enabled=false 只停用回调, 保留已保存的地址和密钥; url=null 用于清除回调地址, 只允许在最终停用时使用.

首次启用或更换地址会同时创建一条 endpoint.test 验证事件, 响应返回 verification_event_id. 配置保存成功不代表接收端已验证通过. 停用只取消 pending 状态的事件, 不会撤回已在投递中的请求, 也不会取消任务或触发退款. 重新启用也不会把已取消的 cancelled 事件恢复回来.

更换地址后, 已产生的历史事件仍使用创建时记录的旧地址, 不会迁移到新地址重投.

写操作不能用于已软删除或带 scope 的 Key; Key 停用, 过期或额度耗尽不影响配置管理. 限流与 Key 生命周期写操作共用: 同一用户每分钟最多 10 次写请求. 请求 JSON 顶层必须是对象, 最多 16384 字节, 正文读取期限 10 秒; 不接受查询参数, 未知字段或重复字段. 请求必须显式提供 api_key_id.

鉴权

Authorizationstring请求头必填

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

请求参数

api_key_idinteger请求体必填

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

enabledboolean请求体

仅启用或禁用回调.

urlstring | null请求体

公网 HTTPS 回调地址, 可为 null.

字段或 JSON 无效返回 400; URL 无效返回 400 (code=16014); 目标 Key 不存在或属于他人统一返回 404; 启用时配置不完整返回 409 (code=16015); mode=off 下需要验证的启用或地址修改返回 409 (code=16016); 触发限流返回 429.

请求示例

curl --request PATCH \
  --url 'https://api.toapis.com/api/v1/webhook' \
  --header 'Authorization: Bearer YOUR_SYSTEM_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{"api_key_id":123,"enabled":false}'

响应示例

{
  "code": 0,
  "message": "",
  "data": {
    "api_key_id": 123,
    "enabled": false,
    "url": null,
    "secret_configured": false,
    "previous_secret_expires_at": null,
    "updated_at": "2026-11-13T00:00:00Z",
    "mode": "enforce",
    "health": {
      "state": "disabled",
      "failure_kind": null,
      "consecutive_failures": 0,
      "suspended_until": null,
      "last_http_status": null,
      "last_failure_at": null
    },
    "verification_event_id": null
  }
}

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