查詢 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.