Webhook

Webhook 是合作夥伴指定的網址，RBM 平台會將訊息和事件發布到這個網址。 這個網址會做為端點，接收含有事件資料的 HTTPS POST 要求。這表示資料會透過 HTTPS 安全地傳送至應用程式。

Webhook 網址可能如下所示： https://[your company name].com/api/rbm-events。 設定 Webhook 後，即可開始接收訊息和事件。

合作夥伴 Webhook 和服務專員 Webhook

你可以在合作夥伴層級或服務專員層級設定 Webhook。

  • 合作夥伴 Webhook 會套用至您維護的每個代理程式。如果代理程式的行為類似，或只有一個代理程式，請使用合作夥伴 Webhook。
  • 服務專員 Webhook 適用於個別服務專員。如果您經營多個行為各異的代理程式，可以為每個代理程式設定不同的 Webhook。

如果您同時設定了合作夥伴 Webhook 和代理程式 Webhook，代理程式 Webhook 會優先套用至特定代理程式，而合作夥伴 Webhook 則會套用至沒有專屬 Webhook 的代理程式。

設定代理程式 Webhook

您會在合作夥伴 Webhook 收到傳送給代理程式的訊息。如要將特定服務專員的訊息傳送至其他 Webhook，請設定服務專員 Webhook。

  1. 開啟 Business Communications 開發人員控制台，然後使用 RBM 合作夥伴 Google 帳戶登入。
  2. 按一下代理程式。
  3. 點選 [Integrations] (整合)。
  4. 在「Webhook」部分，按一下「設定」。
  5. 在「Webhook 端點網址」部分，輸入開頭為「https://」的 Webhook 網址。
  6. 請記下 clientToken 值。您需要這項資訊，才能驗證收到的訊息是否來自 Google。

  7. 將 Webhook 設為接受含有指定 clientToken 參數的 POST 要求，並傳送 200 OK 回應，其中 secret 參數的純文字值會做為回應主體。

    舉例來說，如果 Webhook 收到 POST 要求，且內容如下：

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

    Webhook 應確認 clientToken 值，如果 clientToken 正確，則傳回 200 OK 回應，並將 1234567890 做為回應主體：

    // 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 事件的處理作業以非同步方式進行，且不會阻止 Webhook 傳回 200 OK。

非同步處理 Webhook

請務必不要在 Webhook 本身處理 RBM 事件。處理期間發生任何錯誤或延遲，都可能影響 Webhook 回傳代碼：

同步處理 Webhook

傳送失敗時的行為

當 RBM 從 Webhook 呼叫收到 200 OK 以外的回應時，會使用退避和重試機制。RBM 會增加重試之間的等待時間，最長可達 600 秒。系統會持續重試 7 天，之後就會捨棄郵件。

服務專員層級 Webhook 的影響

RBM 會將合作夥伴的訊息排入一個佇列。如果合作夥伴使用代理商層級的 Webhook，請務必注意，一個 Webhook 失敗會影響其他 Webhook 的傳送。在訊息失敗的回退期間，系統會呼叫其他代理程式的 Webhook。不過，由於系統會將傳送失敗的訊息排入佇列並重試，整體傳送率會下降，其他代理程式也會受到影響。

開發人員務必瞭解這個模型，並據此編寫程式碼，盡可能接受訊息並排入處理佇列，以減少傳回失敗的機會。

後續步驟

設定 Webhook 後，代理程式就能接收測試裝置傳送的訊息。傳送訊息來驗證設定。

下一頁
Dialogflow