Google は AI 技術を使用して、コンテンツをご希望の言語に翻訳しています。AI 翻訳には誤りが含まれる場合があります。

Webhook

Webhook は、パートナーが指定した URL で、RCS for Business プラットフォームがメッセージとイベントを投稿します。この URL は、イベントに関するデータを含む HTTPS POST リクエストを受信するエンドポイントとして機能します。つまり、データは HTTPS 経由で安全にアプリケーションに送信されます。

Webhook URL は https://[your company name].com/api/rbm-events のようになります。Webhook を構成すると、メッセージとイベントの受信を開始できます。

パートナー Webhook とエージェント Webhook

Webhook はパートナーレベルまたはエージェントレベルで設定できます。

パートナーの Webhook は、管理しているすべてのエージェントに適用されます。エージェントの動作が類似している場合や、エージェントが 1 つしかない場合は、パートナーウェブフックを使用します。
エージェント Webhook は個々のエージェントに適用されます。動作が異なる複数のエージェントを運用している場合は、エージェントごとに異なる Webhook を設定できます。

パートナー Webhook とエージェント Webhook の両方を構成している場合、特定のエージェントではエージェント Webhook が優先され、パートナー Webhook は独自 Webhook を持たないエージェントに適用されます。

エージェントの Webhook を構成する

パートナーの Webhook でエージェントに送信されたメッセージを受信します。特定のエージェントのメッセージを別の Webhook に送信する場合は、エージェントの Webhook を設定します。

RCS for Business Developer Console を開き、RCS for Business パートナーの Google アカウントでログインします。
エージェントをクリックします。
[Integrations] をクリックします。
[Webhook] セクションで、[構成] をクリックします。
1. [Webhook エンドポイント] に、「https://」で始まる Webhook URL を入力します。
2. [クライアントトークン] で、clientToken 値を指定します。受信したメッセージが Google から送信されたものであることを確認するために必要です。
注: セキュリティ上の理由により、既存のクライアントトークンを表示することはできません。新しいクライアントトークンを作成するには、それぞれのフィールドに値を入力するか、 [更新] をクリックして乱数値を生成します。

clientToken パラメータと secret パラメータを含む JSON ペイロードで POST リクエストを受け入れるように Webhook を設定します。

{
  "clientToken":"YOURCLIENTTOKEN",
  "secret":"YOURSECRET"
}

リクエストを検証するには、エンドポイントが HTTP 200 OK ステータスコードと、レスポンスボディ内の secret パラメータの未加工の文字列値を返す必要があります。

Webhook 構成の例

たとえば、Webhook が次の本文コンテンツを含む POST リクエストを受信したとします。

  {
  "clientToken":"YOURCLIENTTOKEN",
  "secret":"YOURSECRET"
  }

Webhook は clientToken 値を確認し、clientToken が正しい場合は、レスポンス本文として YOURSECRET を含む 200 OK レスポンスを返します。

  // clientToken from Configure
  const myClientToken = "YOURCLIENTTOKEN";

  // Example endpoint
  app.post("/rbm-webhook", (req, res) => {
    // Use the X-Goog-Webhook-Type header to route requests
    const webhookType = req.header('X-Goog-Webhook-Type');

    if (webhookType === 'verification') {
      const msg = req.body;
      if (msg.clientToken === myClientToken) {
          res.status(200).send(msg.secret);
          return;
      }
    }
    res.send(400);
    // Handle other webhook types
  });

デベロッパーコンソールで、[確認] をクリックします。[確認] をクリックすると、Google から Webhook に POST リクエストが送信されます。リクエストの本文には clientToken と secret がパラメータとして含まれています。RCS for Business がウェブフックを検証すると、ダイアログが閉じます。

リクエストタイプを特定する

Webhook に送信されるすべてのリクエストのリクエストタイプを特定するには、X-Goog-Webhook-Type ヘッダーを使用します。

ヘッダーには次の値を指定できます。

verification: 初期エンドポイント検証プロセスで使用されます。
message_callback: メッセージ関連のイベント（入力、配信通知、ユーザーからの受信メッセージなど）に使用されます。
agent_callback: エージェント固有の管理イベント（エージェントの起動状態の変更など）に使用されます。

受信メッセージを確認する

Webhook は任意の送信者からメッセージを受信できるため、メッセージコンテンツを処理する前に、受信メッセージが Google から送信されたことを確認する必要があります。

受け取ったメッセージが Google から送信されたものかどうかを確認するには、次の手順を行います。

メッセージの X-Goog-Signature ヘッダーを抽出します。これは、メッセージ本文のペイロードのハッシュ化された base64 エンコードコピーです。
リクエストの message.body 要素で RCS for Business ペイロードを Base64 でデコードします。
ウェブフックのクライアントトークン（ウェブフックの設定時に指定したトークン）をキーとして使用し、Base64 でデコードされたメッセージペイロードのバイトの SHA512 HMAC を作成して、結果を Base64 でエンコードします。
X-Goog-Signature ハッシュと作成したハッシュを比較します。
- ハッシュが一致した場合、Google がメッセージを送信したことを確認できます。
- ハッシュが一致しない場合は、既知の正常なメッセージでハッシュ化プロセスを確認します。
  
  ハッシュ化プロセスが正しく機能しているにもかかわらず、不正なメッセージが届いたと思われる場合は、お問い合わせください。

Node.js

  if ((requestBody.hasOwnProperty('message')) && (requestBody.message.hasOwnProperty('data'))) {
    // Validate the received hash to ensure the message came from Google RBM
    const headerHash = req.header('X-Goog-Signature');
    const userEventString = Buffer.from(requestBody.message.data, 'base64');
    const hmac = crypto.createHmac('sha512', myClientToken);
    const genHash = hmac.update(userEventString).digest('base64');

    if (headerHash === genHash) {
      const userEvent = JSON.parse(userEventString);
      const webhookType = req.header('X-Goog-Webhook-Type');

      // Route based on the header type
      if (webhookType === 'message_callback') {
        handleMessage(userEvent);
      } else if (webhookType === 'agent_callback') {
        handleAgentEvent(userEvent);
      }
    } else {
      console.log('Hash mismatch - ignoring message');
      res.sendStatus(401);
      return;
    }
  }

  res.sendStatus(200);

メッセージ処理

Webhook から 200 OK 以外のものを返すと、配信失敗とみなされます。

デベロッパーは、メッセージを高いレートで送信すると、Webhook 通知も高いレートで生成されることに注意し、想定されるレートで通知を処理するようにコードを設計する必要があります。デベロッパーは、ウェブコンテナからの 500 レスポンス、タイムアウト、アップストリームの障害など、失敗レスポンスを引き起こす可能性のある状況を考慮することが重要です。考慮すべき事項は次のとおりです。

DDoS 対策が、想定される Webhook 通知のレートを処理するように構成されていることを確認します。
データベース接続プールなどのリソースが不足して、タイムアウトや 500 レスポンスが発生していないことを確認します。

デベロッパーは、RBM イベントの処理が非同期で行われ、ウェブフックが 200 OK を返せないことがないようにシステムを設計する必要があります。

非同期の Webhook 処理

Webhook 内で RBM イベントを処理しないことが重要です。処理中にエラーや遅延が発生すると、Webhook の戻りコードに影響する可能性があります。

同期 Webhook 処理

配信失敗時の動作

Webhook が 200 OK ステータス以外のものを返した場合、RCS for Business プラットフォームはバックオフと再試行のメカニズムを使用してデータを再配信します。つまり、システムは配信試行の間隔を徐々に増やし、最終的には保留中のメッセージごとに 10 分ごとに 1 回の再試行という最大頻度に達します。再試行サイクルは 7 日間続き、その後、メッセージは完全に削除されます。

エージェントレベルの Webhook の影響

RCS for Business は、パートナーのメッセージを 1 つのキューにキューイングします。1 つのパートナーアカウントに属するすべてのエージェントは、1 つのキューを共有します。そのため、1 つの Webhook で障害が発生すると、キュー全体がブロックされ、すべてのエージェントのユーザーイベントがパートナーに届かなくなる可能性があります。

未確認のメッセージが複数あると、再試行イベントが大幅に増加する可能性があります。たとえば、エージェントが 1,600 件の配信確認応答を認識せず、再試行頻度が 10 分の制限に達すると、1 日あたり約 230,000 件のエラーが発生する可能性があります。

1,600 件のメッセージ × 1 時間あたり 6 回の再試行 × 1 日あたり 24 時間 = 1 日あたり約 230,000 件のエラー

この再試行の量により、共有 Pub/Sub キューがブロックされ、パートナーのすべてのキャンペーンでユーザーイベントの受信が大幅に遅延する可能性があります。

ベストプラクティス

本番環境トラフィックの信頼性を確保し、キューブロッカーを回避するには、次のベストプラクティスに従ってください。

すぐに 200 OK を返す: Webhook はメッセージを受信し、ローカルキューに保存して、5 秒以内に 200 OK レスポンスを返す必要があります。
処理を分離する: 別のバックグラウンドワーカーを使用して、ローカルキューからメッセージロジックを処理します。
テストエージェントをモニタリングする: 開発エージェントは、失敗すると共有パートナーキューをブロックする可能性があるため、本番環境エージェントとして扱います。
テスト専用のアカウント: 本番環境のエージェントには 1 つのデベロッパーアカウントを使用し、テストエージェントには専用のデベロッパーアカウントを使用することが望ましいです。
Google トラフィックを確認する: Google は動的エニーキャスト IP を使用するため、固定 IP の許可リストではなく、リバース DNS または X-Goog-Signature ヘッダーを使用します。手動検証と Google IP 範囲の特定について詳しくは、Google リクエストを検証するのドキュメントと、特にユーザートリガーフェッチャーと Google ユーザートリガーフェッチャーの JSON ファイルをご覧ください。

次のステップ

Webhook を構成すると、エージェントはテストデバイスからメッセージを受信できるようになります。メッセージを送信して、設定を検証します。

Dialogflow