> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thunderphone.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhookエンドポイント

> エンドポイントごとのシークレットとイベントフィルターを使用して、複数の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}/test` | `admin+` | 署名付きテスト配信を送信                |

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

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

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

### 有効なイベントタイプ

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

* `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`に戻してください。
  まだ再試行スケジュールを使い切っていない配信は、中断した時点から再開されます。

***

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

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.thunderphone.com/v1/developer/webhook-endpoints \
    -H "Authorization: Bearer sk_live_YOUR_API_KEY"
  ```
</CodeGroup>

[エンドポイントオブジェクト](#endpoint-object)の配列を返します。

***

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

<CodeGroup>
  ```bash cURL theme={null}
  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 theme={null}
  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"]
  ```
</CodeGroup>

### リクエストフィールド

| フィールド    | 型      | 必須  | 説明                                                                                    |
| -------- | ------ | --- | ------------------------------------------------------------------------------------- |
| `label`  | string | はい  | 1～120文字                                                                               |
| `url`    | string | はい  | HTTPS URL（`localhost` / `127.0.0.1` の場合のみ `http` を許可）                                 |
| `events` | array  | いいえ | 空または省略すると、すべてのイベントを購読します。[有効なイベントタイプ](#valid-event-types)に記載の値を使用する必要があります。重複は削除されます。 |

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

```json theme={null}
{
  "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"
}
```

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

***

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

<CodeGroup>
  ```bash cURL theme={null}
  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"]
    }'
  ```
</CodeGroup>

| フィールド    | 型      | 説明                                                                              |
| -------- | ------ | ------------------------------------------------------------------------------- |
| `label`  | string |                                                                                 |
| `url`    | string |                                                                                 |
| `events` | array  |                                                                                 |
| `status` | string | `active` または `disabled`。サーバーが `failing` とマークしたエンドポイントを再有効化するには `active` を設定します。 |

更新された[エンドポイントオブジェクト](#endpoint-object)を含む `200 OK` を返します。

***

## テスト配信を送信する

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

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-.../test \
    -H "Authorization: Bearer sk_live_YOUR_API_KEY"
  ```
</CodeGroup>

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

```json theme={null}
{
  "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 theme={null}
{
  "success": true,
  "event_id": "2ad6507c-7d19-4498-9b2d-7e8f944ab5a1",
  "event_type": "webhook.test",
  "status": "delivered",
  "response_code": 204,
  "error": ""
}
```

`webhook.test` は合成イベントであり、エンドポイントの `events` 購読には追加できません。
最初の試行が失敗した場合、配信は通常のイベント配信と同じ再試行スケジュールに従います。

***

## エンドポイントを削除

<CodeGroup>
  ```bash cURL theme={null}
  curl -X DELETE https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-... \
    -H "Authorization: Bearer sk_live_YOUR_API_KEY"
  ```
</CodeGroup>

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

***

## 関連項目

<CardGroup cols={2}>
  <Card title="イベントカタログ" icon="list" href="/ja/webhooks/events">
    購読できる `events` 値の完全な一覧です。
  </Card>

  <Card title="Webhook の概要" icon="bolt" href="/ja/webhooks/overview">
    署名の検証と配信のセマンティクス。
  </Card>
</CardGroup>