Webhookエンドポイント

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

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

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

エンドポイント#

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

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

有効なイベントタイプ#

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

• telephony.incoming, telephony.complete, telephony.tool, telephony.turn
• web.incoming, web.complete, web.tool, web.turn
• sms.sent, sms.failed
• sms.received（予約済み。まだ送信されません）
• call.graded, call.data_extracted, call.transfer_completed
• campaign.completed
• issue.reported, issue.escalated
• test-call.completed
• alert.triggered

issue.escalated にはエージェントコンテキストがなく、組織全体の エンドポイントにのみ配信されます。

voice.ready と voice.failed は明示的に選択できません。これらを受信するには、 events: [] を指定して組織全体のエンドポイントを作成してください。空のイベント リストは、明示的に選択する必要がある telephony.turn と web.turn を除く、すべての サポート対象イベントを受信します。

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

• 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"

エンドポイントオブジェクトの配列を返します。 ?agent_id=42 を渡すと、そのエージェントを対象とするエンドポイントのみを返します。

エージェント対象のエンドポイント#

組織全体のエンドポイントは、一致するすべてのイベントを受信します。 agent_id を指定したエンドポイントは、そのエージェントが処理した通話に関する一致イベントのみを 受信します。alert.triggered など、エージェントコンテキストを持たないイベントは到達しません。 これらのエンドポイントは、エージェントビルダーのWebhookセクションから作成・管理することもできます。

エンドポイントを作成#

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

リクエストフィールド#

Endpoint オブジェクトに加え、生の署名キーを含む追加のトップレベル 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 -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"]
  }'

更新された Endpoint オブジェクトを含む 200 OK を返します。

署名シークレットをローテーションする#

紛失した、または漏洩した可能性がある場合などに、エンドポイントの署名シークレットを置き換えます。 エージェントスコープのエンドポイントでは、ダッシュボードも使用できます。エージェントの Webhook セクションを開き、 エンドポイントで シークレットを再生成 を選択します。組織全体のエンドポイントは API を介してローテーションします。

curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-.../rotate-secret \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

200 OK を返します。

{
  "endpoint": { "id": "c4d5e6f7-...", "secret_hint": "7f3a…c21d", "...": "..." },
  "secret": "7f3a90b2c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5c21d",
  "rotated_endpoint_ids": ["c4d5e6f7-..."]
}

テスト配信を送信#

通常の配信パイプラインを使用して、合成 webhook.test イベントを1つのエンドポイントに送信します。正規化された JSON シリアル化、両方の署名ヘッダー、配信記録、再試行管理が含まれます。
このテストは、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 サブスクリプションには追加できません。最初の試行に失敗した場合、ThunderPhone は約 1 分後に 1 回再試行してから停止します。配信はその後、配信をデバッグで status: "failed" と表示されます。テスト配信によってエンドポイントが failing になることはありません。

実際のイベント形式に対するトリガーを設定するには、任意の event_type を渡します。配信は引き続き合成であり、"sample": true が含まれます。 通話関連のサンプルでは、call_id: 0 と agent_id: 0 が使用されます。

curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-.../test \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event_type":"call.graded"}'

event_type には、有効なイベントタイプの任意の値を指定できます。 省略すると、汎用的な webhook.test の動作が維持されます。

エンドポイントを削除#

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

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

配信をデバッグ#

Webhook が送信されなかったと判断する前に、 GET /v1/developer/webhook-deliveriesを確認してください。 通話 ID、URL オリジン、HTTP ステータス、試行回数、許可リストに登録された失敗カテゴリ、次回の再試行時刻を含む、両方の Webhook システムの最近の試行が表示されます。イベントペイロード、文字起こし、保存されたエラーテキスト、レスポンス本文、URL パスは返されません。

同じ最近の履歴は、エージェント → エージェントを選択 → Webhook → 最近の配信 でも確認できます。行には、最新の試行で使用されたエンドポイントラベルと URL オリジンが表示されます。これは不変の監査ログではなく運用状態です。エンドポイントを削除すると、その配信行も削除されます。

n8n の 404 では、まずワークフローが有効であること、POST を受け付けること、テスト URL ではなく本番用 Webhook URL を使用していることを確認してください。401 または 403 は認証または署名検証を示します。タイムアウトは送信先のレイテンシーまたは可用性を示し、TLS エラーは証明書チェーン、ホスト名、または有効期限を示します。

関連#