Webhook

Webhook は、RCS for Business プラットフォームが メッセージ と イベントを投稿する、パートナー指定の URL です。 この 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 に配信する場合は、エージェント Webhook を設定します。

  1. Business Communications Developer Console を開き、RCS for Business パートナーの Google アカウントでログインします。
  2. エージェントをクリックします。
  3. [Integrations] をクリックします。
  4. [Webhook] で [Configure] をクリックします。
  5. [Webhook endpoint URL] に、 「https://」で始まる Webhook URL を入力します。
  6. clientToken の値をメモします。受信したメッセージが Google から送信されたものであることを確認するために 必要です。

  7. 指定した clientToken パラメータを含む POST リクエストを受け入れ、secret パラメータのプレーン テキスト値をレスポンス本文として 200 OK レスポンスを送信するように Webhook を構成します。

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

    {
  "clientToken":"SJENCPGJESMGUFPY",
  "secret":"1234567890"
}

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

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

// Example endpoint
app.post("/rbm-webhook", (req, res) => {
  const msg = req.body;
  if (msg.clientToken === myClientToken) {
      res.status(200).send(msg.secret);
      return;
  }
  res.send(400);
});

  8. Developer Console で [Verify] をクリックします。RCS for Business が Webhook を検証すると、ダイアログが閉じます。

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

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

受信したメッセージが Google から送信されたものであることを確認する手順は次のとおりです。

  1. メッセージの X-Goog-Signature ヘッダーを抽出します。これは、メッセージ本文のペイロードのハッシュ化された base64 エンコード コピーです。
  2. リクエストの message.body 要素で、RCS for Business のペイロードを base64 でデコードします。
  3. Webhook のクライアント トークン（Webhook の設定時に指定）をキーとして使用し、base64 でデコードされたメッセージ ペイロードのバイトの SHA512 HMAC を作成し、結果を base64 でエンコードします。
  4. 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
    let userEventString = Buffer.from(requestBody.message.data, 'base64');
    let hmac = crypto.createHmac('sha512', CLIENT_TOKEN);
    let data = hmac.update(userEventString);
    let genHash = data.digest('base64');
    let headerHash = req.header('X-Goog-Signature');

    if (headerHash === genHash) {
      let userEvent = JSON.parse(userEventString);

      console.log('userEventString: ' + userEventString);
      handleMessage(userEvent);
    } else {
      console.log('hash mismatch - ignoring message');
    }
  }

  res.sendStatus(200);

メッセージ処理

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

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

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

デベロッパーは、RBM イベントの処理が非同期で行われ、Webhook が 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