Skip to main content
ThunderPhoneは、通話中にイベントが発生するとサーバーにHTTP POST リクエストを送信します。たとえば、着信の開始、通話の終了、評価実行の完了、アラートの発生などです。配信モデルは2種類あります。

Webhookエンドポイント(推奨)

複数のURL、エンドポイントごとのシークレット、エンドポイントごとのイベントフィルター、 および自動再試行。 GET/POST/PATCH/DELETE /v1/developer/webhook-endpoints で管理します。

単一URLのレガシーWebhook

組織ごとに1つのURL。ブロッキング構成のやり取りを含む、 通話ライフサイクルイベントを送信します。GET/PUT /v1/webhook で管理します。
イベントカタログにある10種類すべてのイベントは、Webhookエンドポイントを通じて 配信されます。6種類の通話ライフサイクルイベント (telephony.incomingtelephony.completetelephony.toolweb.incomingweb.completeweb.tool)は、レガシーの単一URL Webhookにも送信されます。レガシーURLと一致するエンドポイントの両方がある場合、 イベントは両方のパスで受信されます。ブロッキング動作 (telephony.incoming / web.incoming の構成のやり取りおよびWebhookモードの ツールディスパッチ)は、レガシーパスでのみ提供されます。 エンドポイントへの配信はすべて、応答を待たない通知です。

ペイロード形式

エンドポイントへの配信は、dataevent_idtype を含むJSONオブジェクトです。
event_id は、送信されたイベントごとに一意です。再試行時も、 さらにイベントを受信するすべてのエンドポイント間でも同一です。この値で重複を排除してください。 レガシーの単一URL Webhookは、同じ typedata を送信しますが、 event_id含まれません
通信上では、すべての本文が正規形式でシリアライズされます。キーはアルファベット順に並び、 空白は含まれず、UTF-8を使用します。これらのドキュメントにある整形済みの例は、 読みやすさのためだけに用意されています。 イベントタイプとペイロードフィールドの完全な一覧については、 イベントカタログを参照してください。

署名の検証

すべてのリクエストには、生のリクエスト 本文に対する HMAC-SHA256 署名が X-ThunderPhone-Signature ヘッダーに含まれます。署名キーはエンドポイントの secret(またはレガシー配信の場合は組織レベルの webhook secret)です。

手順

  1. 解析を行うに、生のリクエスト本文を読み取ります。
  2. hmac_sha256(secret, body).hexdigest() を計算します。
  3. X-ThunderPhone-Signature ヘッダーと定数時間で比較します。
ThunderPhone は送信するバイト列そのものに署名します。これらのバイト列は 正規化された JSON シリアライズ(キーをソートし、区切り文字をコンパクト化)です。そのため、 生の本文に対する検証は常に機能します。フレームワークから解析済み JSON しか取得できない場合も、 キーをソートして区切り文字をコンパクト化して再シリアライズすれば、同一のバイト列が生成されます。両方の方法は検証ガイドで説明しています。

配信セマンティクス

これらのセマンティクスは エンドポイント 配信に適用されます。レガシーの単一 URL Webhook は、再試行なしの単一同期試行です。
各イベントは直ちに 1 回試行されます。2xx 応答はすべて 配信を確認します。それ以外の結果(非 2xx、 接続エラー、タイムアウト)の場合、最初の試行から 1 分、5 分、30 分、2 時間、6 時間、 12 時間、24 時間後に再試行します。24 時間にわたる 合計 8 回の試行です。すべての試行が失敗すると、配信は停止し、エンドポイントは Webhook エンドポイントstatus="failing" としてマークされます。ペイロードが永続的に受理されたら、できるだけ早く 2xx を返してください。処理は非同期で行います。
配信順序はベストエフォートです。実際にはイベントが発行された 順序で配信しますが、失敗時の再試行によって順序が入れ替わる場合があります。 常に call_id / オブジェクト ID によって重複排除と整合性確認を行ってください。
配信は 少なくとも 1 回です。確認できなかった応答の後の再試行により、 イベントが重複する場合があります。すべての再試行には同じ event_id が含まれるため、処理済み ID を保存し、重複をスキップしてください。event_id は エンドポイント間でも共有されます。同じイベントを購読する 2 つのエンドポイントは、同じ event_id を受け取ります。
エンドポイント配信は、試行ごとに 30 秒のタイムアウトがあります。 レガシーパスでは、ライブ通話の動作を制御するブロッキングリクエスト、つまり telephony.incoming / web.incomingの 設定交換は 10 秒後にタイムアウトします。ただし、応答が遅いと通話の応答が遅延するため、 数秒以内の応答を目標にしてください。Webhook モードのツールディスパッチでは 20 秒を使用できます。
送信 Webhook は ThunderPhone のクラウド IP アドレス範囲から送信されます。 ファイアウォールで許可リストが必要な場合は、サポートにお問い合わせください。最新の 範囲を共有します。

レガシー Webhook とエンドポイントベース Webhook の選択

新しい統合では、エンドポイントベースの Webhook を通じてイベントを処理してください。通話応答時に動的に通話を設定する場合、または Webhook モードのツールディスパッチを使用する場合にのみ、レガシー URL を維持または追加してください。これらの リクエスト/レスポンス交換はレガシーパスでのみ実行されます。

関連

イベントカタログ

すべてのイベントタイプとそのペイロード。

Webhook エンドポイント

複数のエンドポイント、イベントフィルター、シークレットを管理します。

telephony.incoming / web.incoming

通話を設定するためにサーバーが応答する必要があるブロッキングリクエスト。

telephony.complete / web.complete

文字起こし、録音、メトリクスを含む通話後のペイロード。