Webhookエンドポイント

エンドポイントベースの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`	stringの配列	購読するイベントタイプ（有効な値を参照）。空の配列はすべてのイベントを購読
`status`	string	`active`、`disabled`（手動で一時停止）、または`failing`（配信が1回も2xxを受け取らずに24時間の再試行スケジュールをすべて使い切った場合に自動設定）
`secret_hint`	string	署名シークレットの先頭4文字と末尾4文字を省略記号（`a1b2…9f0e`）でつないだ値。完全な値を公開せずに、ローカルに保存したシークレットと照合するのに十分
`created_at`, `updated_at`	timestamp

エンドポイントの完全なsecretは、作成時に1回だけ返され、以後は返されません。安全に保管してください。失った場合は、エンドポイントを削除して再作成してください。

有効なイベントタイプ

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

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

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

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

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

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

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

エンドポイントを作成する

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"]
  }'

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`	string	はい	1～120文字
`url`	string	はい	HTTPS URL（`localhost` / `127.0.0.1` の場合のみ `http` を許可）
`events`	array	いいえ	空または省略すると、すべてのイベントを購読します。有効なイベントタイプに記載の値を使用する必要があります。重複は削除されます。

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

{
  "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"
}

secret は作成時にのみ返されます。以降の GET レスポンスには secret_hint のみが含まれます。レスポンスを閉じる前に、完全な値をシークレットマネージャーへコピーしてください。

エンドポイントを更新する

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`	string
`url`	string
`events`	array
`status`	string	`active` または `disabled`。サーバーが `failing` とマークしたエンドポイントを再有効化するには `active` を設定します。

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

テスト配信を送信する

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

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 -X DELETE https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-... \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

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

イベントカタログ

購読できる events 値の完全な一覧です。

Webhook の概要

署名の検証と配信のセマンティクス。

Webhooks

Function Tools

Webhookエンドポイント

エンドポイント

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

有効なイベントタイプ

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

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

エンドポイントを作成する

リクエストフィールド

エンドポイントを更新する

テスト配信を送信する

エンドポイントを削除

関連項目

イベントカタログ

Webhook の概要

​エンドポイント

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

​有効なイベントタイプ

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

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

​エンドポイントを作成する

​リクエストフィールド

​エンドポイントを更新する

​テスト配信を送信する

​エンドポイントを削除

​関連項目

イベントカタログ

Webhook の概要

エンドポイント

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

有効なイベントタイプ

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

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

エンドポイントを作成する

リクエストフィールド

エンドポイントを更新する

テスト配信を送信する

エンドポイントを削除

関連項目