Webhook

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

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

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

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

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

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

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

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

  1. Business Communications デベロッパー コンソールを開き、RBM パートナーの Google アカウントでログインします。
  2. エージェントをクリックします。
  3. [Integrations] をクリックします。
  4. [Webhook] で [構成] をクリックします。
  5. [Webhook エンドポイント 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. デベロッパー コンソールで、[確認] をクリックします。RBM が Webhook を検証すると、ダイアログが閉じます。

受信メールを確認する

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

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

  1. メッセージの X-Goog-Signature ヘッダーを抽出します。これは、メッセージ本文ペイロードのハッシュ化された base64 エンコード コピーです。
  2. リクエストの message.body 要素で RBM ペイロードを Base64 でデコードします。
  3. ウェブフックのクライアント トークン（ウェブフックの設定時に指定）をキーとして使用し、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 イベントの処理が非同期で行われ、ウェブフックが 200 OK を返せないことがないようにシステムを設計する必要があります。

非同期の Webhook 処理

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

同期 Webhook 処理

配信失敗時の動作

RBM は、Webhook 呼び出しから 200 OK 以外のレスポンスを受け取ると、バックオフと再試行のメカニズムを使用します。RBM は、再試行間の待機時間を最大 600 秒まで増やします。再試行は 7 日間継続され、その後メッセージは破棄されます。

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

RBM は、パートナーのメッセージを 1 つのキューにキューイングします。パートナーがエージェント レベルの Webhook を使用している場合、1 つの Webhook の失敗が他の Webhook への配信に影響することに注意してください。他のエージェントに属する Webhook は、失敗したメッセージのバックオフ期間中に呼び出されます。ただし、失敗したメッセージが再試行のためにキューに登録されると、全体的な配信率が低下し、他のエージェントに影響します。

デベロッパーがこのモデルを理解し、それに応じてコードを記述することが重要です。可能な限り、メッセージを受け入れて処理のためにキューに登録し、失敗を返す機会を最小限に抑えます。

次のステップ

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

次へ
Dialogflow