Webhook 設定の更新 | ToAPIs Documentation

PATCH

/api/v1/webhook

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

動作

指定キーのコールバック URL と有効状態を設定・変更します. enabled と url の少なくとも一方が必要で, 省略したフィールドは現値を保持します. 有効化する前にシークレットと公開 HTTPS コールバック URL の設定が必要です. enabled=false 単体はコールバックを無効化するだけで, 保存済みの URL とシークレットは残ります.

url=null はコールバック URL の消去で, 最終的に無効化する場合のみ許可されます.

初回の有効化または URL 変更では endpoint.test 検証イベントも同時に作成され, レスポンスに verification_event_id が返ります. 設定の保存成功は受信側の検証成功を意味しません. 無効化は pending 状態のイベントを取り消すだけで, 配信中のリクエストは取り消さず, タスクのキャンセルや返金も行いません.

再有効化しても cancelled イベントは復元されません. URL を変更しても, 生成済みの過去イベントは作成時に記録された旧 URL のままで, 新しい URL へ再配信されません.

論理削除済みや scope 付きのキーには書き込めません. 無効, 期限切れ, 枯渇のキーの設定管理は可能です. レート制限はキーのライフサイクル書き込みと共用で, 同一ユーザーあたり毎分最大 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 URL または null.

フィールドや JSON が不正な場合は 400, URL が不正な場合は 400 (code=16014), 対象キーが存在しないか他人のものは 404, 有効化時の設定不足は 409 (code=16015), mode=off で検証が必要な有効化や URL 変更は 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 設定の取得を参照してください.