Webhook 設定の取得 | ToAPIs Documentation

GET

/api/v1/webhook

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

動作

指定キーの Webhook 設定を読み取り, コールバック URL, 有効状態, 直近の配送ヘルスを確認できます. Webhook 設定はモデルキーごとに 1 件で, ソフト削除済みキーも読み取れます. シークレット設定済みかどうかは secret_configured のみ返し, シークレット本文は返しません. 未設定の URL と時刻は null です.

管理 API の時刻は 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, 対象キーが存在しないか他人のものは 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 でコールバック URL を設定し enabled=true を渡します. 初回の有効化や URL 変更では endpoint.test 検証イベントが作成され, レスポンスに verification_event_id が返ります.
POST /api/v1/webhook/test でテストイベントを送信するか, GET /api/v1/webhook/events/{event_id} で検証・配信結果を確認します.

署名検証

すべてのコールバックリクエストには 3 つのヘッダーが付きます: X-ToAPIs-Webhook-Id (イベント ID), X-ToAPIs-Webhook-Timestamp (Unix 秒タイムスタンプ), X-ToAPIs-Webhook-Signature (署名).

検証ではイベント ID, タイムスタンプ, 生のリクエストボディを . で連結して event_id.timestamp.raw_body を作り, 保存した secret で HMAC-SHA256 を計算し, 署名ヘッダーの v1= の後の 16 進ダイジェストと比較します.

必ず生のリクエストボディのバイト列で検証し, JSON を解析して再シリアライズしないでください. シークレットローテーション期間中は署名ヘッダーにカンマ区切りの複数の v1= 値が含まれることがあり, いずれかが一致すれば有効です. 受信側はイベント ID で重複を排除します.

コールバック payload と署名タイムスタンプは Unix 秒で, 管理 API の時刻は RFC 3339 です.