列出 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 設定.