mcpField
S
setup-webhook

setup-webhook

github.com/bolna-ai開発366 回インストール3 日前に更新
リポジトリ

setup-webhook について

setup-webhook は、通話ステータスと実行データを受け取る Bolna の HTTP Webhook を設定するスキルです。受信側の構築、ペイロード処理、重複配信への対応、ローカルテストを扱います。

主な機能

  1. 01Agent の Webhook URL 設定
  2. 02通話・実行の更新受信
  3. 03ペイロードの冪等処理
  4. 04ローカル受信側のテスト

活用シーン

  1. 01実行更新のデータベース保存
  2. 02CRM やサポートのワークフロー起動
  3. 03未配信データの取得と補完

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/bolna-ai/skills --skill setup-webhook

インストール後、Claude Code で/setup-webhookを入力して読み込まれたか確認します。

同梱ファイルscripts/webhook_receiver.py

詳細

Bolna Webhook のセットアップ

Bolna が送信する内容

通話ステータスと実行データが変更されると、Bolna は設定された webhook URL に HTTP POST リクエストを送信します。Webhook のペイロードは実行オブジェクトとして扱い、配信漏れや重複配信を照合するには、同じ実行 ID に対して get-executions を使用してください。

設定場所

  • ダッシュボード：エージェントの Analytics タブにある「Push all execution data to webhook」。
  • API：エージェントの作成時またはパッチ適用時に agent_config.webhook_url を設定します。

API パッチ

curl --request PATCH \
  --url "https://api.bolna.ai/v2/agent/$AGENT_ID" \
  --header "Authorization: Bearer $BOLNA_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "agent_config": {
      "webhook_url": "https://example.com/bolna/webhook"
    }
  }'

受信側の要件

  • 本番環境では、公開 HTTPS URL を使用します。
  • POST JSON を受け付けます。
  • 速やかに 2xx を返します。
  • execution_id または id をキーに、冪等に保存します。
  • 取り消せない後続アクションを実行する前に、ペイロードの形式を検証します。
  • ファイアウォールを設定する場合は、許可リストに登録する前に、Bolna の最新ドキュメントで webhook の送信元 IP を確認してください。

ローカルテスト用の受信側

python3 setup-webhook/scripts/webhook_receiver.py --port 8080

ngrok や Cloudflare Tunnel などのトンネルで公開し、公開 HTTPS URL を Bolna に設定します。

最小限のペイロード処理パターン

  1. JSON を解析します。
  2. 実行 ID、ステータス、エージェント ID、電話番号、文字起こし、録音 URL、抽出データを取り出します。
  3. 実行 ID をキーにデータベースへアップサートします。
  4. 関連する終端ステータス（通常は completed、failed、no-answer、busy、error）になった後にのみ、自動化を実行します。
  5. ペイロードが不完全な場合は、GET /executions/{execution_id} を呼び出します。

一般的な自動化

  • 要約と録音を CRM に送信します。
  • 抽出データに基づいてリードのステータスを更新します。
  • 引き継ぎに失敗した後、サポートチケットを作成します。
  • Make、Zapier、n8n、またはカスタムコードを使って WhatsApp、SMS、メールを送信します。
  • queued、ringing、in-progress、completed からライブダッシュボードのカードを作成します。

許可リストに登録する送信元 IP

Bolna は単一の送信元 IP から webhook を配信します。

13.203.39.153

この IP をサーバーのファイアウォールの許可リストに追加します。エンドポイントの機密性が高い場合は、それ以外からの接続を拒否してください。

ペイロードの形式

Webhook の本文は GET /executions/{execution_id} と同一です。すべてのフィールドについては https://raw.githubusercontent.com/bolna-ai/skills/main/references/execution-payload.md を、ステータスが発生する順序については https://raw.githubusercontent.com/bolna-ai/skills/main/references/call-statuses.md を参照してください。

冪等性

status の遷移（scheduled → queued → in-progress → completed）に伴い、同じ実行に対して複数回 webhook が配信されることがあります。（execution_id、status）で重複を除外してください。execution_id だけで重複を除外すると後続の更新が破棄されるため、決して使用しないでください。

関連項目

  • https://raw.githubusercontent.com/bolna-ai/skills/main/references/execution-payload.md — ペイロード内のすべてのフィールド。
  • https://raw.githubusercontent.com/bolna-ai/skills/main/references/call-statuses.md — ステータスの順序、終端ステータスのフィルター。
  • get-executions — webhook の配信に失敗した実行の過去データを取得します。
  • debug-bolna-calls — 配信漏れを診断します。

コメント

Markdown 対応