Webhook

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

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

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

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

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

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

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

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

ビジネスコミュニケーションデベロッパーコンソールを開き、RBM パートナーの Google アカウントでログインします。
エージェントをクリックします。
[Integrations] をクリックします。
[Webhook] で [構成] をクリックします。
[Webhook のエンドポイント URL] に、「https://」で始まる Webhook URL を入力します。
clientToken の値をメモします。これは、受信したメッセージが Google から送信されたものであることを確認するために必要です。
指定された 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);
});
```
Developers Console で [確認] をクリックします。RBM が Webhook を確認すると、ダイアログが閉じます。

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

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

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

メッセージの X-Goog-Signature ヘッダーを抽出します。これは、メッセージ本文ペイロードのハッシュ化された base64 エンコードコピーです。
リクエストの message.body 要素内の RBM ペイロードを Base64 でデコードします。
webhook のクライアントトークン（webhook の設定時に指定したトークン）をキーとして、Base64 でデコードされたメッセージペイロードのバイト値の SHA512 HMAC を作成し、結果を Base64 でエンコードします。
X-Goog-Signature ハッシュと作成したハッシュを比較します。
- ハッシュが一致した場合、Google がメッセージを送信したことが確認されます。
- ハッシュが一致しない場合は、正常なメッセージでハッシュ化プロセスを確認します。
  
  ハッシュ化プロセスが正しく機能していて、不正に送信されたと思われるメッセージが届いた場合は、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 レスポンス、タイムアウト、アップストリーム障害など、失敗レスポンスを引き起こす可能性のある状況を考慮することが重要です。考慮すべき点は次のとおりです。

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

配信エラー時の動作

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

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

RBM は、パートナーのメッセージを 1 つのキューにキューに登録します。パートナーがエージェントレベルの Webhook を使用している場合、1 つの Webhook でエラーが発生すると、他の Webhook への配信に影響することが重要です。他のエージェントに属する Webhook は、失敗したメッセージのバックオフ期間中に呼び出されます。ただし、失敗したメッセージが再試行のためにキューに追加されると、全体的な配信率が低下し、他のエージェントにも影響が及ぶ可能性があります。

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

次のステップ

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