POST リクエストを送信します。たとえば、着信の開始、通話の終了、評価実行の完了、アラートの発生などです。配信モデルは2種類あります。
Webhookエンドポイント(推奨)
複数のURL、エンドポイントごとのシークレット、エンドポイントごとのイベントフィルター、
および自動再試行。
GET/POST/PATCH/DELETE /v1/developer/webhook-endpoints で管理します。単一URLのレガシーWebhook
組織ごとに1つのURL。ブロッキング構成のやり取りを含む、
通話ライフサイクルイベントを送信します。
GET/PUT /v1/webhook で管理します。telephony.incoming、telephony.complete、telephony.tool、
web.incoming、web.complete、web.tool)は、レガシーの単一URL
Webhookにも送信されます。レガシーURLと一致するエンドポイントの両方がある場合、
イベントは両方のパスで受信されます。ブロッキング動作
(telephony.incoming / web.incoming の構成のやり取りおよびWebhookモードの
ツールディスパッチ)は、レガシーパスでのみ提供されます。
エンドポイントへの配信はすべて、応答を待たない通知です。
ペイロード形式
エンドポイントへの配信は、data、event_id、type を含むJSONオブジェクトです。
event_id は、送信されたイベントごとに一意です。再試行時も、
さらにイベントを受信するすべてのエンドポイント間でも同一です。この値で重複を排除してください。
レガシーの単一URL Webhookは、同じ type と data を送信しますが、
event_id は含まれません。
署名の検証
すべてのリクエストには、生のリクエスト 本文に対する HMAC-SHA256 署名がX-ThunderPhone-Signature ヘッダーに含まれます。署名キーはエンドポイントの
secret(またはレガシー配信の場合は組織レベルの webhook secret)です。
手順
- 解析を行う前に、生のリクエスト本文を読み取ります。
hmac_sha256(secret, body).hexdigest()を計算します。X-ThunderPhone-Signatureヘッダーと定数時間で比較します。
配信セマンティクス
これらのセマンティクスは エンドポイント 配信に適用されます。レガシーの単一 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 秒を使用できます。送信元 IP アドレス
送信元 IP アドレス
送信 Webhook は ThunderPhone のクラウド IP アドレス範囲から送信されます。
ファイアウォールで許可リストが必要な場合は、サポートにお問い合わせください。最新の
範囲を共有します。
レガシー Webhook とエンドポイントベース Webhook の選択
新しい統合では、エンドポイントベースの
Webhook を通じてイベントを処理してください。通話応答時に動的に通話を設定する場合、または
Webhook モードのツールディスパッチを使用する場合にのみ、レガシー URL を維持または追加してください。これらの
リクエスト/レスポンス交換はレガシーパスでのみ実行されます。
関連
イベントカタログ
すべてのイベントタイプとそのペイロード。
Webhook エンドポイント
複数のエンドポイント、イベントフィルター、シークレットを管理します。
telephony.incoming / web.incoming
通話を設定するためにサーバーが応答する必要があるブロッキングリクエスト。
telephony.complete / web.complete
文字起こし、録音、メトリクスを含む通話後のペイロード。