Webhook イベント一覧 | ToAPIs Documentation

GET

/api/v1/webhook/events

中国本土のユーザー向け: 中国本土のユーザーは https://api.toapis.cn を API エンドポイント (Base URL)としてご利用ください. 本ドキュメント内の例では https://api.toapis.com を https://api.toapis.cn に置き換えてください.

動作

Webhook コールバックの配送履歴を返し, 到達確認と失敗の切り分けに使います. api_key_id を省略すると配下の全イベントを返し, 指定した場合は自分の通常モデルキーかを検証します (ソフト削除済みでも可).

既定は直近 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, 絞り込みキーが存在しないか他人のものは 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 設定の取得を参照してください.