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

# Webhook

> サーバーで OneInbox のリアルタイムイベントを受信する — ポーリング不要。

## Webhook の仕組み

通話イベントが発生すると、OneInbox はイベントペイロードを含む HTTP POST をサーバーに送信します。サーバーは数秒以内に `2xx` で応答する必要があります — 応答がない場合、OneInbox は再送します。

Webhook を設定すれば、`GET /v1/calls/<id>` を繰り返しポーリングする必要はありません。OneInbox がイベント発生の瞬間にデータをプッシュします。

***

## Webhook を作成する

サーバー上の URL と受信したいイベントを指定して Webhook をセットアップします。OneInbox はそれらのイベントが発火するたびにその URL に POST リクエストを送信します。

```bash theme={null}
curl -X POST https://api.oneinbox.ai/v1/webhooks \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Call events",
    "url": "https://your-server.com/webhooks/oneinbox",
    "events": ["call.started", "call.ended", "call.analyzed", "call.failed", "call.recording.available", "transcript.partial", "transcript.final"]
  }'
```

```json theme={null}
{
  "id": "wh_abc123",
  "name": "Call events",
  "url": "https://your-server.com/webhooks/oneinbox",
  "events": ["call.started", "call.ended", "transcript.final"]
}
```

`id` を保存しておいてください — Webhook の更新や削除に必要です。

***

## サポートされているイベント

| イベント                       | 発火タイミング                                  |
| -------------------------- | ---------------------------------------- |
| `call.started`             | 通話が接続し、エージェントがセッションを開始したとき               |
| `call.ended`               | 通話が終了したとき — エージェントまたは発信者がハングアップ          |
| `call.analyzed`            | 通話後に AI 分析（サマリー、結果）が準備完了したとき             |
| `call.failed`              | 通話の接続に失敗したとき                             |
| `call.recording.available` | 通話録音が準備完了してアクセス可能になったとき                  |
| `transcript.partial`       | アクティブな通話中の部分的なトランスクリプト更新                 |
| `transcript.final`         | 完全なトランスクリプトが準備完了したとき（`call.ended` の後に発火） |

***

## イベントペイロード

### `call.started`

通話が接続し、エージェントがセッションを開始したときに発火します。通話開始時刻をログに記録したり、CRM で「通話中」の更新をトリガーするために使用します。

```json theme={null}
{
  "event": "call.started",
  "call_id": "call_abc123",
  "agent_id": "agt_abc123",
  "to_number": "+919876543210",
  "from_number": "+15739693824",
  "created_at": "2026-06-01T10:00:00Z"
}
```

### `call.ended`

通話が終了したときに発火します。このペイロードには AI が生成した結果とサマリーが含まれます — CRM 更新、リードルーティング、レポートに最もよく使われるイベントです。

```json theme={null}
{
  "event": "call.ended",
  "call_id": "call_abc123",
  "agent_id": "agt_abc123",
  "status": "completed",
  "duration_seconds": 87,
  "to_number": "+919876543210",
  "from_number": "+15739693824",
  "outcome": "Appointment Booked",
  "ai_summary": "Caller agreed to a product demo on Thursday at 3pm.",
  "analysis": {
    "summary": "Caller agreed to a product demo on Thursday at 3pm."
  }
}
```

### `call.analyzed`

通話終了後、AI がサマリーと結果の生成を完了したときに発火します。通話結果に基づいた CRM 更新やリードルーティングをトリガーするために使用します。

```json theme={null}
{
  "event": "call.analyzed",
  "call_id": "call_abc123",
  "agent_id": "agt_abc123",
  "outcome": "Appointment Booked",
  "ai_summary": "Caller agreed to a product demo on Thursday at 3pm."
}
```

### `call.failed`

通話の接続に失敗したときに発火します。失敗のログ記録、リトライのトリガー、チームへのアラートに使用します。

```json theme={null}
{
  "event": "call.failed",
  "call_id": "call_abc123",
  "agent_id": "agt_abc123",
  "to_number": "+919876543210",
  "from_number": "+15739693824",
  "reason": "no-answer"
}
```

### `call.recording.available`

通話録音が処理されてアクセス可能になったときに発火します。通話後に録音を保存または共有するために使用します。

```json theme={null}
{
  "event": "call.recording.available",
  "call_id": "call_abc123",
  "recording_url": "https://storage.oneinbox.ai/recordings/call_abc123.mp3"
}
```

### `transcript.partial`

部分的なトランスクリプト更新とともにアクティブな通話中に発火します。リアルタイムモニタリングやライブエージェントアシストに使用します — 部分的なトランスクリプトは通話が続くにつれて変わる場合があることに注意してください。

```json theme={null}
{
  "event": "transcript.partial",
  "call_id": "call_abc123",
  "messages": [
    { "role": "agent", "content": "Hi! How can I help you today?" },
    { "role": "user",  "content": "I'd like to book a demo." }
  ]
}
```

### `transcript.final`

完全なトランスクリプトが準備完了したら `call.ended` の後に発火します。データベースへの記録や CRM への送信など、完全なメッセージごとの会話ログが必要な場合に使用します。

```json theme={null}
{
  "event": "transcript.final",
  "call_id": "call_abc123",
  "messages": [
    { "role": "agent", "content": "Hi! How can I help you today?" },
    { "role": "user",  "content": "I'd like to book a demo." },
    { "role": "agent", "content": "Of course! Let me get that booked for you." }
  ]
}
```

***

## Webhook をテストする

本番稼働前にサーバーがイベントを正しく受信していることを確認するためにテスト配信を送信します：

```bash theme={null}
curl -X POST https://api.oneinbox.ai/v1/webhooks/<webhook_id>/test \
  -H "Authorization: Bearer <api_key>"
```

サーバーはサンプルペイロードを含むテスト POST を受信するはずです。サーバーのログを確認して、受信できていてエンドポイントが `2xx` を返していることを確認してください。

***

## 通話ごとの Webhook 上書き

グローバルな Webhook 設定を変更せずに、特定の通話のイベントを別の URL に送ることができます。これは異なるキャンペーンやバッチを別々のダウンストリームシステムにルーティングする場合に便利です — 例えばインバウンド通話用の URL とアウトバウンド通話用の URL を分ける場合。

通話を作成するときに `webhook_url` を渡します：

```bash theme={null}
curl -X POST https://api.oneinbox.ai/v1/calls \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "<agent_id>",
    "to_number": "+919876543210",
    "from_number": "+15739693824",
    "webhook_url": "https://your-server.com/this-campaign-only"
  }'
```

この通話のイベントは、設定済みのグローバル Webhook の代わりに（または追加で）`webhook_url` に送られます。

***

## Webhook を管理する

### すべての Webhook を一覧表示

アカウント内のすべての Webhook を取得します。更新または削除が必要な Webhook の `id` を見つけるために使用します。

```bash theme={null}
curl https://api.oneinbox.ai/v1/webhooks \
  -H "Authorization: Bearer <api_key>"
```

### Webhook を更新する

Webhook の URL、名前、イベント、またはステータスを変更します。

```bash theme={null}
curl -X PATCH https://api.oneinbox.ai/v1/webhooks/<webhook_id> \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{ "events": ["call.started", "call.ended", "transcript.final"] }'
```

| フィールド    | 内容                                                  |
| -------- | --------------------------------------------------- |
| `name`   | Webhook の名前変更                                       |
| `url`    | 配信エンドポイントの変更                                        |
| `events` | 購読イベントの全リストを置換                                      |
| `status` | `"active"` または `"inactive"` — Webhook を削除せずに配信を一時停止 |

### Webhook を削除する

Webhook を永続的に削除します。OneInbox はその URL へのイベント送信を即座に停止します。

```bash theme={null}
curl -X DELETE https://api.oneinbox.ai/v1/webhooks/<webhook_id> \
  -H "Authorization: Bearer <api_key>"
```

### 配信履歴を確認する

Webhook の配信試行ログを取得します。特定のイベントがサーバーに届いたか確認したり、配信失敗を診断するのに便利です。最新の試行から順に返され、各行に `response_status`、`response_body`、`error` が含まれます。

```bash theme={null}
curl "https://api.oneinbox.ai/v1/webhooks/<webhook_id>/deliveries?limit=50" \
  -H "Authorization: Bearer <api_key>"
```

***

## API リファレンス

[Webhook 作成](/api-reference/webhooks/create-webhook) · [Webhook 一覧](/api-reference/webhooks/list-webhooks) · [Webhook 更新](/api-reference/webhooks/update-webhook) · [テスト配信](/api-reference/webhooks/test-webhook-delivery)