更新 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 設定.