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

# 通話 Webhook

> 通話イベントを独自のエンドポイントで受信します。

通話 Webhook は、各通話のイベントをサーバー上の HTTPS エンドポイントに送信します。送信されるのは、通話の開始時、各ターン、通話の終了時、そして終了後の要約です。通話のログ記録や後続処理のトリガーに使用できます。

## Webhook を追加する

> [tab] Playground
>
> 1. エージェントを開き、**Advanced** に移動します。
> 2. **Context** の下で、**Post-call webhooks** の横にある **Add webhook** をクリックします。
> 3. **Name**、**URL**、任意の **Authentication Secret** を入力します。
> 4. **Add** をクリックします。
>
> Webhook は **Publish** を行わなくても、新しい通話にすぐ適用されます。
>
> ![Advanced ページの Context グループ。Post-call webhooks とタイムゾーンの設定が表示されている](https://mintcdn.com/cartesia-2650f86a/rNXFyzq4MzdYRAHq/assets/images/agents/advanced-context.png?fit=max\&auto=format\&n=rNXFyzq4MzdYRAHq\&q=85\&s=d0d8dace5c8e9aa09c7c67bf4e4168b1)
>
> Advanced ページの Post-call webhooks。

> [tab] API
>
> [`POST /agents/webhooks`](https://docs.cartesia.ai/ja-jp/api-reference/agents/webhooks/create) で Webhook を作成します：
>
> ```bash theme={null}
> curl -X POST "https://api.cartesia.ai/agents/webhooks" \
>   -H "X-API-Key: $CARTESIA_API_KEY" \
>   -H "Cartesia-Version: 2026-08-14" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "display_name": "Call events",
>     "url": "https://example.com/cartesia/events",
>     "secret": "YOUR_WEBHOOK_SECRET"
>   }'
> ```
>
> 次に、[`PATCH /v1/agents/{agent_id}`](https://docs.cartesia.ai/ja-jp/api-reference/agents/update) でその `id` をエージェントにアタッチします：
>
> ```json theme={null}
> { "config": { "event_webhook_id": "agent_webhook_..." } }
> ```
>
> デタッチするには、`event_webhook_id` を `null` に設定します。

1 つのエージェントに設定できる Webhook は 1 つで、その Webhook がすべてのイベントタイプを受信します。複数のエージェントで 1 つの Webhook を共有できます。

## リクエストを検証する

各リクエストは `POST` で、`Content-Type: application/json` と、設定したシークレットを含む `X-Webhook-Secret` ヘッダーが付与されます。ヘッダーが一致しないリクエストは拒否してください。

## イベント

| `type` | 送信されるタイミング |
| - | - |
| `call_started` | 通話が接続されたとき。 |
| `call_turn` | ターンが終了したとき。各ツール呼び出しは、`tool_calls` を含む個別のアシスタントターンとして届きます。 |
| `call_completed` | 通話が正常に終了したとき。 |
| `call_failed` | 通話が失敗したとき、または応答がなかったとき。失敗した発信では、その前に `call_started` が送信されない場合があります。 |
| `post_call_analysis` | 通話終了後、1〜2 文の要約の準備ができたとき。誰も発話しなかった通話には要約が作成されません。 |

処理しないイベントタイプは無視してください。Cartesia は今後イベントタイプを追加する場合があります。

## ペイロード

すべてのイベントに共通するフィールドは次のとおりです：

| フィールド | 説明 |
| - | - |
| `type` | イベントタイプ。 |
| `call_id`、`agent_id`、`webhook_id` | 通話、エージェント、Webhook の ID。 |
| `webhook_request_id` | イベントごとに一意で、再試行間では同じ値です。重複の除外に使用します。 |
| `timestamp` | イベントが送信された日時（RFC 3339 形式）。 |
| `body` | `call_completed` と `call_failed` ではトランスクリプト、`call_turn` ではターン、それ以外では `null`。 |

上記のイベントには、さらに詳細オブジェクトが 1 つ含まれます：

* `call_started`、`call_completed`、`call_failed` の `call`：通話全体。[Get Call](https://docs.cartesia.ai/ja-jp/api-reference/agents/calls/get-call.md) が返すものと同じオブジェクトです。後者 2 つでは `end_reason` も設定されます。
* `call_turn` の `turn`：`role`、`text`、`start_timestamp`、`end_timestamp`、`was_interrupted`。ツールを呼び出すターンでは、各呼び出しの `name`、`arguments`、`result` を含む `tool_calls` も含まれます。
* `post_call_analysis` の `analysis`：`summary`。

```json call_turn theme={null}
{
  "type": "call_turn",
  "call_id": "ac_3kF9mN2pQ8rT1vX6",
  "agent_id": "agent_Fo7pKNBUwLZxrTd6jvhpaE",
  "webhook_id": "agent_webhook_...",
  "webhook_request_id": "...",
  "timestamp": "2026-10-30T18:02:11Z",
  "body": {
    "id": 3,
    "role": "user",
    "text": "I want to reschedule.",
    "start_timestamp": 3.5,
    "end_timestamp": 5.8,
    "was_interrupted": false
  },
  "turn": {
    "id": 3,
    "role": "user",
    "text": "I want to reschedule.",
    "start_timestamp": 3.5,
    "end_timestamp": 5.8,
    "was_interrupted": false
  }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.