Webhookエンドポイント

エンドポイントごとのシークレットとイベントフィルターで複数のWebhook URLを管理します。

エンドポイントベースのWebhookシステムでは、組織ごとに複数の 送信先を登録できます。各送信先には、それぞれ固有のシークレット、ステータス、イベントタイプのサブセットに対するサブスクリプションを設定できます。これはすべての新規統合で推奨されるモデルです。

後方互換性のために維持されているものの、組織ごとに1つのURLしかサポートしない従来の単一URL Webhookと比較してください。

エンドポイント

メソッド	パス	必要なロール	説明
`GET`	`/v1/developer/webhook-endpoints`	`admin+`	エンドポイントを一覧表示
`POST`	`/v1/developer/webhook-endpoints`	`admin+`	エンドポイントを作成
`PATCH`	`/v1/developer/webhook-endpoints/{endpoint_id}`	`admin+`	ラベル / URL / イベント / ステータスを更新
`DELETE`	`/v1/developer/webhook-endpoints/{endpoint_id}`	`admin+`	エンドポイントを削除
`POST`	`/v1/developer/webhook-endpoints/{endpoint_id}/test`	`admin+`	署名付きテスト配信を送信

エンドポイントオブジェクト

{
  "id": "c4d5e6f7-...",
  "label": "Production — Call events",
  "url": "https://example.com/thunderphone/hook",
  "events": ["telephony.incoming", "telephony.complete"],
  "status": "active",
  "secret_hint": "a1b2…9f0e",
  "created_at": "2026-04-20T18:24:10.113Z",
  "updated_at": "2026-04-20T18:24:10.113Z"
}

フィールド	型	説明
`id`	UUID	エンドポイントID
`label`	string	表示名、1～120文字
`url`	string	HTTPS URL。開発用として`http://localhost`を許可
`events`	array of string	サブスクライブするイベントタイプ（有効な値を参照）。空の配列は、明示指定が必要なターンごとのイベント（`telephony.turn` / `web.turn`）を除くすべてのイベントをサブスクライブします
`status`	string	`active`、`disabled`（手動で一時停止）、または`failing`（配信が1回も2xxを受信せずに24時間の再試行スケジュールを使い切った場合に自動設定）
`secret_hint`	string	署名シークレットの先頭4文字と末尾4文字を省略記号付きで表示（`a1b2…9f0e`）。完全な値を公開せずにローカルに保存したシークレットと照合できます
`created_at`, `updated_at`	timestamp

有効なイベントタイプ

eventsはこの完全一致のセットに対して検証されます。リスト外の値は 400を返します。各タイプのペイロード形式についてはイベントカタログを参照してください。

telephony.incoming, telephony.complete, telephony.tool, telephony.turn
web.incoming, web.complete, web.tool, web.turn
call.graded
issue.reported
test-call.completed
alert.triggered

エンドポイントのステータス

active — 配信は通常どおり送信されます。
disabled — PATCHで手動停止されています。リクエストは送信されません。 disabledエンドポイントのステータスが変更されることはありません。activeへの戻しは常に手動で行います。
failing — エンドポイントへの配信が、2xxを一度も受信せずに再試行スケジュール全体（24時間で8回の試行）を使い切ると自動的に設定されます。失敗中のエンドポイントには、それ以降のトラフィックは送信されません。エンドポイントを修正したら、PATCHでステータスをactiveに戻します。再試行スケジュールがまだ終了していない配信は、中断した地点から再開されます。

エンドポイントを一覧表示

cURL

curl https://api.thunderphone.com/v1/developer/webhook-endpoints \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

エンドポイントオブジェクトの配列を返します。

エンドポイントを作成

cURL

curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label":  "Production — Call events",
    "url":    "https://example.com/thunderphone/hook",
    "events": ["telephony.incoming", "telephony.complete"]
  }'

Python

result = requests.post(
    "https://api.thunderphone.com/v1/developer/webhook-endpoints",
    headers={"Authorization": "Bearer sk_live_YOUR_API_KEY"},
    json={
        "label":  "Production — Call events",
        "url":    "https://example.com/thunderphone/hook",
        "events": ["telephony.incoming", "telephony.complete"],
    },
).json()
secret = result["secret"]
endpoint_id = result["id"]

リクエストフィールド

フィールド	型	必須	説明
`label`	文字列	はい	1～120文字
`url`	文字列	はい	HTTPS URL（`localhost` / `127.0.0.1` の場合のみ `http` を使用可能）
`events`	配列	いいえ	空または省略した場合、明示的な購読が必要な `telephony.turn` / `web.turn` を除くすべてのイベントを購読します。有効なイベントタイプに記載されている値を使用してください。重複は削除されます

エンドポイントオブジェクトに加え、生の署名キーを含む追加のトップレベル secret フィールドを含む 201 Created を返します。これは48文字の16進数文字列です。

{
  "id": "c4d5e6f7-…",
  "label": "Production — Call events",
  "url": "https://example.com/thunderphone/hook",
  "events": ["telephony.incoming", "telephony.complete"],
  "status": "active",
  "secret_hint": "a1b2…9f0e",
  "created_at": "2026-04-20T18:24:10.113Z",
  "updated_at": "2026-04-20T18:24:10.113Z",
  "secret": "a1b2c37e08d94f5b16a2c8d90e7f3a4b5c6d7e8f90a19f0e"
}

エンドポイントを更新

cURL

curl -X PATCH https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-... \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label":  "Production — Call + Grade events",
    "events": ["telephony.incoming", "telephony.complete", "call.graded"]
  }'

フィールド	型	説明
`label`	文字列
`url`	文字列
`events`	配列
`status`	文字列	`active` または `disabled`。サーバーが `failing` とマークしたエンドポイントを再度有効にするには、`active` を設定します

更新されたエンドポイントオブジェクトを含む 200 OK を返します。

テスト配信を送信

通常の配信パイプラインを使用して、1 つのエンドポイントに合成 webhook.test イベントを送信します。正規化された JSON シリアル化、X-ThunderPhone-Signature、配信記録、再試行管理が含まれます。テストは、選択したエンドポイントの events フィルターにかかわらず、そのエンドポイントを対象とします。

cURL

curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-.../test \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

エンドポイントは次のようなエンベロープを受信します。

{
  "data": {
    "message": "ThunderPhone webhook test",
    "sent_at": "2026-07-17T20:12:34.567890+00:00"
  },
  "event_id": "2ad6507c-7d19-4498-9b2d-7e8f944ab5a1",
  "type": "webhook.test"
}

送信先がエラーを返した場合でも、API は最初の試行後に 200 OK を返します。配信結果は success、status、response_code、error で確認します。

{
  "success": true,
  "event_id": "2ad6507c-7d19-4498-9b2d-7e8f944ab5a1",
  "event_type": "webhook.test",
  "status": "delivered",
  "response_code": 204,
  "error": ""
}

webhook.test は合成イベントであり、エンドポイントの events サブスクリプションには追加できません。最初の試行が失敗した場合、通常のイベント配信と同じ再試行スケジュールに従って配信されます。

エンドポイントを削除

cURL

curl -X DELETE https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-... \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

204 No Content を返します。URL への配信は直ちに停止し、実行中の再試行は中止されます。