---
title: "Webhookエンドポイント"
description: "エンドポイントごとのシークレットとイベントフィルターを使用して、複数のWebhook URLを管理します。"
---
エンドポイントベースのWebhookシステムでは、組織ごとに**複数の**送信先を登録できます。各送信先には、それぞれ固有のシークレット、ステータス、およびイベントタイプの一部へのサブスクリプションを設定できます。これは、すべての新規統合で推奨されるモデルです。
後方互換性のために維持されているものの、組織ごとに1つのURLしかサポートしない[従来の単一URL Webhook](/api-reference/organizations#legacy-single-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}/rotate-secret` | `admin+` | 署名シークレットを置き換え |
| `POST` | `/v1/developer/webhook-endpoints/{endpoint_id}/test` | `admin+` | 署名付きテスト配信を送信 |
| `GET` | `/v1/developer/webhook-deliveries` | `admin+` | 最近のエンドポイントおよびレガシー配信結果を確認 |
## エンドポイントオブジェクト
```json
{
"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"
}
```
| フィールド | 型 | 説明 |
|-------|------|-------------|
| `id` | UUID | エンドポイントID |
| `label` | string | 表示名、1～120文字 |
| `url` | string | HTTPS URL。開発用には `http://localhost` を使用可能 |
| `events` | stringの配列 | 購読するイベントタイプ（[有効な値](#valid-event-types)を参照）。空の配列は、明示指定専用のターンごとのイベント（`telephony.turn` / `web.turn`）を除くすべてのイベントを購読 |
| `status` | string | `active`、`disabled`（手動で一時停止）、または `failing`（配信が1件の2xxも受け取らずに24時間の再試行スケジュールを完了すると自動設定） |
| `agent_id` | integer \| null | このエンドポイントの対象となるエージェント。`null` は組織全体を意味します |
| `agent_name` | string \| null | 対象エージェントの名前。組織全体のエンドポイントでは `null` |
| `secret_hint` | string | 署名シークレットの先頭4文字と末尾4文字を省略記号付きで表示（`a1b2…9f0e`）。完全な値を公開せずに、ローカルに保存したシークレットと照合するのに十分な情報 |
| `paused_at` | timestamp \| null | ThunderPhone がエンドポイントを `failing` に設定した日時。`active` または `disabled` の間は `null` |
| `pause_last_error` | string | エンドポイントが一時停止されたときの最後の配信エラー。例: `HTTP 503: Service Unavailable`。`failing` 以外では空 |
| `pause_undelivered_count` | integer \| null | 一時停止時にカウントされる、エンドポイントの最後の正常な配信以降に配信されていないイベント数 |
| `created_at`, `updated_at` | timestamp | |
エンドポイントの完全な `secret` は作成時に**一度だけ**返され、
以後は返されません。安全に保管してください。紛失した場合は、
[ローテーション](#rotate-the-signing-secret)して新しいものを取得してください。
### 有効なイベントタイプ
`events` はこの完全一致のセットに対して検証されます。リスト外の値は
`400` を返します。各タイプのペイロード形式については、
[イベントカタログ](/ja/webhooks/events)を参照してください。
- `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` に戻します。再試行スケジュールがまだ終了していない配信は、中断した時点から再開されます。
---
## エンドポイントを一覧表示
```bash cURL
curl https://api.thunderphone.com/v1/developer/webhook-endpoints \
-H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
[エンドポイントオブジェクト](#endpoint-object)の配列を返します。
`?agent_id=42` を渡すと、そのエージェントを対象とするエンドポイントのみを返します。
### エージェント対象のエンドポイント
組織全体のエンドポイントは、一致するすべてのイベントを受信します。
`agent_id` を指定したエンドポイントは、そのエージェントが処理した通話に関する一致イベントのみを
受信します。`alert.triggered` など、エージェントコンテキストを持たないイベントは到達しません。
これらのエンドポイントは、エージェントビルダーの**Webhook**セクションから作成・管理することもできます。
---
## エンドポイントを作成
```bash 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 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` | string | はい | 1～120文字 |
| `url` | string | はい | HTTPS URL（`localhost` / `127.0.0.1` のみ `http` を許可） |
| `events` | array | いいえ | 空または省略すると、明示的な登録が必要な `telephony.turn` / `web.turn` を除くすべてのイベントを登録します。[有効なイベントタイプ](#valid-event-types)に記載された値を使用する必要があり、重複は削除されます |
| `agent_id` | integer \| null | いいえ | この組織内のエージェントに配信範囲を限定します。組織全体のエンドポイントには省略するか `null` を使用します |
[Endpoint オブジェクト](#endpoint-object)に加え、生の署名キーを含む追加のトップレベル `secret` フィールドを含む `201 Created` を返します。署名キーは48文字の16進数文字列です。
```json
{
"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` のみが含まれます。レスポンスを閉じる前に、完全な値をシークレット
マネージャーへコピーしてください。
---
## エンドポイントを更新
```bash 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` | string | |
| `url` | string | |
| `events` | array | |
| `status` | string | `active` または `disabled`。サーバーが `failing` とマークしたエンドポイントを再度有効にするには `active` を設定します |
| `agent_id` | integer \| null | エージェント ID を設定してエンドポイントの範囲を限定するか、`null` を設定して組織全体を対象にします |
更新された [Endpoint オブジェクト](#endpoint-object)を含む `200 OK` を返します。
---
## 署名シークレットをローテーションする
紛失した、または漏洩した可能性がある場合などに、エンドポイントの署名シークレットを置き換えます。
エージェントスコープのエンドポイントでは、ダッシュボードも使用できます。エージェントの **Webhook** セクションを開き、
エンドポイントで **シークレットを再生成** を選択します。組織全体のエンドポイントは
API を介してローテーションします。
```bash cURL
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 '{}'
```
| フィールド | 型 | 必須 | 説明 |
|-------|------|----------|-------------|
| `include_copies` | boolean | いいえ | デフォルトは `true`。同じ URL と同じ現在のシークレットを持つ組織内の他のエンドポイント（他のエージェント上にあるこのエンドポイントのコピーなど）にも新しいシークレットを付与するため、1 つの受信側で 1 つのシークレットを使用して検証を継続できます。 |
`200 OK` を返します。
```json
{
"endpoint": { "id": "c4d5e6f7-...", "secret_hint": "7f3a…c21d", "...": "..." },
"secret": "7f3a90b2c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5c21d",
"rotated_endpoint_ids": ["c4d5e6f7-..."]
}
```
| フィールド | 型 | 説明 |
|-------|------|-------------|
| `endpoint` | object | 新しい `secret_hint` を含む [Endpoint オブジェクト](#endpoint-object)。 |
| `secret` | string | 新しい署名シークレット。このレスポンスでのみ返されます。 |
| `rotated_endpoint_ids` | UUID の配列 | 新しいシークレットを使用するようになったすべてのエンドポイント。 |
古いシークレットは直ちに使用されなくなります。再試行を含む次回の配信は、
新しいシークレットで署名されます。受信側に新しいシークレットが設定されるまで、
配信は署名チェックに失敗します。受信側がこれらに非 2xx ステータスで応答した場合、
通常の 24 時間スケジュールで再試行されるため、速やかに受信側を更新してください。受信側を段階的に
ロールアウトする場合は、ロールアウト中に両方のシークレットを受け入れるようにしてください。SDK の
検証ヘルパーはシークレットのリストを受け取ります（[Webhook 署名を検証する](/ja/guides/verify-webhook-signatures)を参照）。
---
## テスト配信を送信
通常の配信パイプラインを使用して、合成 `webhook.test` イベントを1つのエンドポイントに送信します。正規化された JSON シリアル化、両方の署名ヘッダー、配信記録、再試行管理が含まれます。
このテストは、`events` フィルターに関係なく選択したエンドポイントを対象にします。
```bash cURL
curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-.../test \
-H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
エンドポイントは次のようなエンベロープを受信します。
```json
{
"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` で確認します。
```json
{
"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 回再試行してから停止します。配信はその後、[配信をデバッグ](#debug-deliveries)で `status: "failed"` と表示されます。テスト配信によってエンドポイントが `failing` になることはありません。
実際のイベント形式に対するトリガーを設定するには、任意の
`event_type` を渡します。配信は引き続き合成であり、`"sample": true` が含まれます。
通話関連のサンプルでは、`call_id: 0` と `agent_id: 0` が使用されます。
```bash
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` には、[有効なイベントタイプ](#valid-event-types)の任意の値を指定できます。
省略すると、汎用的な `webhook.test` の動作が維持されます。
---
## エンドポイントを削除
```bash 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 への配信は直ちに停止し、
進行中の再試行は中止されます。
---
## 配信をデバッグ
Webhook が送信されなかったと判断する前に、
[`GET /v1/developer/webhook-deliveries`](/api-reference/webhook-deliveries)を確認してください。
通話 ID、URL オリジン、HTTP ステータス、試行回数、許可リストに登録された失敗カテゴリ、次回の再試行時刻を含む、両方の Webhook システムの最近の試行が表示されます。イベントペイロード、文字起こし、保存されたエラーテキスト、レスポンス本文、URL パスは返されません。
同じ最近の履歴は、**エージェント → エージェントを選択 → Webhook →
最近の配信** でも確認できます。行には、最新の試行で使用されたエンドポイントラベルと URL オリジンが表示されます。これは不変の監査ログではなく運用状態です。エンドポイントを削除すると、その配信行も削除されます。
n8n の `404` では、まずワークフローが有効であること、`POST` を受け付けること、テスト URL ではなく本番用 Webhook URL を使用していることを確認してください。`401` または `403` は認証または署名検証を示します。タイムアウトは送信先のレイテンシーまたは可用性を示し、TLS エラーは証明書チェーン、ホスト名、または有効期限を示します。
---
## 関連
サブスクライブ可能な `events` 値の完全な一覧。
署名検証と配信セマンティクス。