通話 Webhook

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

Webhook を追加する

Playground
API

エージェントを開き、Advanced に移動します。
Context の下で、Post-call webhooks の横にある Add webhook をクリックします。
Name、URL、任意の Authentication Secret を入力します。
Add をクリックします。

Webhook は Publish を行わなくても、新しい通話にすぐ適用されます。

Advanced ページの Context グループ。Post-call webhooks とタイムゾーンの設定が表示されている — Advanced ページの Post-call webhooks。

POST /agents/webhooks で Webhook を作成します：

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} でその id をエージェントにアタッチします：

{ "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 が返すものと同じオブジェクトです。後者 2 つでは end_reason も設定されます。
call_turn の turn：role、text、start_timestamp、end_timestamp、was_interrupted。ツールを呼び出すターンでは、各呼び出しの name、arguments、result を含む tool_calls も含まれます。
post_call_analysis の analysis：summary。

call_turn

{
  "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
  }
}

はじめに

エージェント管理

ツール

オーディオ統合

テレフォニー

評価

移行

Webhook を追加する

リクエストを検証する

イベント

ペイロード

​Webhook を追加する

​リクエストを検証する

​イベント

​ペイロード

Webhook を追加する

リクエストを検証する

イベント

ペイロード