Webhook を使用すると、チャット セッション中に該当するイベントが発生するたびに（チャットの作成、メッセージの受信、チャットの転送やエスカレーションなど）、Apps API からアプリケーションにリアルタイム通知が送信されます。Webhook を使用すると、API をポーリングするのではなく、チャット アクティビティが発生したときに反応できます。
Webhook は、Apps API のチャット セッションを対象としています。コンタクト センター AI プラットフォームは、サポートされているすべてのアプリの API チャット Webhook イベントを、構成した単一の Webhook URL に HTTP POST リクエストとして配信します。イベントごとのサブスクリプションはありません。
始める前に
- Webhook を設定するには、管理者であるか（またはデベロッパー設定を編集する権限を持つロールが割り当てられている）必要があります。
- HTTP
POSTリクエストを受信できるエンドポイントを準備します。Webhook URL は HTTPS を使用する必要があります。
Webhook を有効にする
Webhook を有効にすると、コンタクト センター AI プラットフォームは構成済みの URL に webhook イベントを配信し、URL フィールドと Secret フィールドが表示されます。Webhook がオフの場合、イベントは送信されません。
Webhook を有効にする手順は次のとおりです。
- CCAI Platform ポータルで、[設定 > デベロッパー設定] をクリックします。[設定] メニューが表示されない場合は、 [メニュー] をクリックします。
- [Webhook] ペインに移動し、[Webhook] 切り替えボタンをオンにします。
Webhook URL を構成する
- [URL] に、Webhook エンドポイントを入力します。
- エンドポイントが HTTPS を使用し、
POSTリクエストを受信できることを確認します。コンタクト センター AI プラットフォームは、サポートされているすべてのイベントをこの単一の URL に送信します。
署名シークレットを生成する
コンタクト センター AI プラットフォームはすべての Webhook リクエストに署名するため、アプリケーションはリクエストがコンタクト センター AI プラットフォームから送信されたことを確認できます。署名は X-Signature リクエスト ヘッダーで、署名タイムスタンプは X-Signature-Timestamp で送信されます。署名シークレットは最大 2 つまで構成できます。
- プライマリ シークレット: Webhook リクエストの署名に使用されるメイン トークン。
- セカンダリ シークレット: オプションの 2 つ目のトークン。セカンダリ シークレットが設定されている場合、コンタクト センター AI プラットフォームは両方のシークレットで各リクエストに署名します。これにより、イベントを見逃すことなくシークレットをローテーションできます。
各シークレットを個別に生成します。シークレットを生成する手順は次のとおりです。
- CCAI Platform ポータルで、[設定 > デベロッパー設定] をクリックします。[設定] メニューが表示されない場合は、 [メニュー] をクリックします。
- [Webhook] ペインに移動します。
- [プライマリ シークレット] セクションで、[生成] をクリックします。[コピー] をクリックしてシークレットをコピーし、安全に保管します。シークレット全体は、生成直後にのみ表示されます。その後、マスクされます。
- 省略可: [セカンダリ シークレット] セクションで、[生成] をクリックします。[コピー] をクリックしてシークレットをコピーし、安全に保管します。
- 警告ダイアログで確認します。新しいシークレットはすぐに有効になるため、置き換えられたシークレットをまだ使用しているものはすべて失敗します。
署名シークレットをローテーションする
プライマリ シークレットが存在する場合、[シークレットをローテーション] アクションが使用可能になります。シークレットを定期的にローテーションすることは、セキュリティのベスト プラクティスです。コンタクト センター AI プラットフォームは、プライマリ シークレットとセカンダリ シークレットの両方で各リクエストに署名するため、配信を中断することなくローテーションできます。
- CCAI Platform ポータルで、[設定 > デベロッパー設定] をクリックします。[設定] メニューが表示されない場合は、 [メニュー] をクリックします。
- プライマリ シークレットとセカンダリ シークレットの両方が設定されていることを確認します。
- [シークレットをローテーション] をクリックして、プライマリ シークレットとセカンダリ シークレットを入れ替えます。
- 新しいアクティブ シークレットに対して署名を確認するようにアプリケーションを更新します。重複期間中、コンタクト センター AI プラットフォームは構成された両方のシークレットで各リクエストに署名するため、どちらか一方を受け入れれば配信が中断されることはありません。
構成を保存する
[保存] を選択して、Webhook の有効状態と URL を適用します。シークレットの生成またはローテーションはすぐに有効になり、保存操作は必要ありません。コンタクト センター AI プラットフォームは、Webhook が有効になり、Webhook URL とプライマリ シークレットが設定された後にイベントの配信を開始します。
アプリケーションが受け取るもの
Webhook を有効にすると、コンタクト センター AI プラットフォーム は、ライフサイクルの変更、参加者のアクティビティ、メッセージ、転送、エスカレーション、ウェブフォーム、終了警告など、サポートされている各チャット イベントに対して HTTP POST リクエストを送信します。各リクエスト本文は、event_type、timestamp、chat_id、イベント固有の body を含む JSON エンベロープです。