Webhook

Webhook là một URL do đối tác chỉ định, nơi nền tảng RBM đăng tin nhắn và sự kiện. URL này đóng vai trò là một điểm cuối nhận các yêu cầu POST qua HTTPS chứa dữ liệu về các sự kiện. Điều này có nghĩa là dữ liệu được gửi đến ứng dụng của bạn một cách an toàn qua HTTPS.

URL webhook có thể có dạng như sau: https://[your company name].com/api/rbm-events. Sau khi định cấu hình webhook, bạn có thể bắt đầu nhận tin nhắn và sự kiện.

Webhook của đối tác và webhook của nhân viên hỗ trợ

Bạn có thể định cấu hình webhook ở cấp đối tác hoặc cấp nhân viên hỗ trợ.

Webhook đối tác của bạn áp dụng cho mọi tác nhân mà bạn duy trì. Nếu các trợ lý ảo của bạn có hành vi tương tự nhau hoặc nếu bạn chỉ có một trợ lý ảo, hãy sử dụng webhook đối tác.
Webhook của nhân viên hỗ trợ áp dụng cho từng nhân viên hỗ trợ. Nếu vận hành nhiều tác nhân có hành vi riêng biệt, bạn có thể đặt một webhook riêng cho từng tác nhân.

Nếu bạn đã định cấu hình cả webhook đối tác và webhook nhân viên hỗ trợ, thì webhook nhân viên hỗ trợ sẽ được ưu tiên trên nhân viên hỗ trợ cụ thể của webhook đó, trong khi webhook đối tác sẽ áp dụng cho mọi nhân viên hỗ trợ không có webhook riêng.

Định cấu hình webhook cho nhân viên hỗ trợ

Bạn nhận được tin nhắn gửi đến nhân viên hỗ trợ tại webhook của đối tác. Nếu bạn muốn tin nhắn cho một nhân viên hỗ trợ cụ thể đến một webhook khác, hãy đặt một webhook cho nhân viên hỗ trợ.

Mở Business Communications Developer Console rồi đăng nhập bằng Tài khoản Google của đối tác RBM.
Nhấp vào nhân viên hỗ trợ.
Nhấp vào Tích hợp.
Đối với Webhook, hãy nhấp vào Định cấu hình.
Đối với URL điểm cuối webhook, hãy nhập URL webhook bắt đầu bằng "https://".
Ghi lại giá trị clientToken. Bạn cần khoá này để xác minh rằng thư bạn nhận được là của Google.
Định cấu hình webhook để chấp nhận yêu cầu POST có tham số clientToken được chỉ định và gửi phản hồi 200 OK có giá trị văn bản thuần tuý của tham số secret làm nội dung phản hồi.

Ví dụ: nếu webhook của bạn nhận được yêu cầu POST có nội dung sau đây
```
{
  "clientToken":"SJENCPGJESMGUFPY",
  "secret":"1234567890"
}
```
thì webhook của bạn sẽ xác nhận giá trị clientToken và nếu clientToken là chính xác, hãy trả về phản hồi 200 OK với 1234567890 làm nội dung phản hồi:
```
// 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);
});
```
Trong Developer Console, hãy nhấp vào Xác minh. Khi RBM xác minh webhook của bạn, hộp thoại sẽ đóng.

Xác minh tin nhắn đến

Vì webhook có thể nhận tin nhắn từ mọi người gửi, nên bạn phải xác minh rằng Google đã gửi tin nhắn đến trước khi xử lý nội dung tin nhắn.

Để xác minh rằng Google đã gửi một thông báo mà bạn nhận được, hãy làm theo các bước sau:

Trích xuất tiêu đề X-Goog-Signature của thư. Đây là bản sao đã băm, được mã hoá base64 của tải trọng nội dung thư.
Giải mã Base64 cho tải trọng RBM trong phần tử message.body của yêu cầu.
Sử dụng mã thông báo ứng dụng của webhook (bạn đã chỉ định khi thiết lập webhook) làm khoá, hãy tạo một HMAC SHA512 gồm các byte của tải trọng thông báo được giải mã base-64 và mã hoá kết quả bằng base64.
So sánh hàm băm X-Goog-Signature với hàm băm mà bạn đã tạo.
- Nếu các hàm băm khớp nhau, tức là bạn đã xác nhận rằng Google gửi tin nhắn.
- Nếu các hàm băm không khớp, hãy kiểm tra quy trình băm của bạn trên một thông báo đã biết là tốt.
  
  Nếu quy trình băm của bạn hoạt động bình thường và bạn nhận được một thông báo mà bạn cho rằng được gửi cho bạn một cách gian lận, hãy liên hệ với chúng tôi.

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);

Xử lý tin nhắn

Việc trả về bất kỳ giá trị nào khác ngoài 200 OK từ webhook được xem là lỗi giao hàng.

Nhà phát triển phải lưu ý rằng việc gửi tin nhắn với tốc độ cao sẽ tạo ra thông báo webhook với tốc độ cao và phải thiết kế mã để xử lý thông báo ở tốc độ dự kiến. Các nhà phát triển cần cân nhắc những tình huống có thể gây ra phản hồi thất bại, bao gồm cả phản hồi 500 từ vùng chứa web, thời gian chờ hoặc lỗi ngược dòng. Những điều cần cân nhắc bao gồm:

Xác minh rằng các biện pháp bảo vệ chống DDoS được định cấu hình để xử lý tốc độ thông báo webhook dự kiến.
Xác nhận rằng các tài nguyên như nhóm kết nối cơ sở dữ liệu không hết và tạo ra thời gian chờ hoặc phản hồi 500.

Nhà phát triển nên thiết kế hệ thống của mình sao cho quá trình xử lý các sự kiện RBM diễn ra không đồng bộ và không ngăn webhook trả về 200 OK.

Xử lý webhook không đồng bộ

Điều quan trọng là bạn không xử lý sự kiện RBM trong chính webhook. Mọi lỗi hoặc sự chậm trễ trong quá trình xử lý đều có thể ảnh hưởng đến mã trả về của webhook:

Xử lý webhook đồng bộ

Hành vi khi không gửi được

RBM sử dụng cơ chế giảm tốc và thử lại khi nhận được phản hồi khác 200 OK từ lệnh gọi webhook. RBM sẽ tăng thời gian chờ giữa các lần thử lại lên tối đa 600 giây. Hệ thống sẽ tiếp tục thử lại trong 7 ngày, sau đó thư sẽ bị loại bỏ.

Ý nghĩa của webhook ở cấp nhân viên hỗ trợ

RBM xếp tin nhắn cho một đối tác vào một hàng đợi. Nếu đối tác đang sử dụng webhook ở cấp tác nhân, thì bạn cần lưu ý rằng việc một webhook không hoạt động sẽ ảnh hưởng đến việc phân phối cho các webhook khác. Webhook thuộc về các nhân viên hỗ trợ khác sẽ được gọi trong khoảng thời gian tạm ngưng của một thông báo không gửi được. Tuy nhiên, khi các thông báo không gửi được xếp hàng để thử lại, tỷ lệ gửi tổng thể sẽ giảm và các tác nhân khác sẽ bị ảnh hưởng.

Điều quan trọng là nhà phát triển phải hiểu rõ mô hình này và viết mã cho phù hợp – trong phạm vi có thể, chấp nhận thông báo và đưa thông báo vào hàng đợi để xử lý nhằm giảm thiểu cơ hội trả về lỗi.

Các bước tiếp theo

Sau khi bạn định cấu hình webhook, nhân viên hỗ trợ có thể nhận tin nhắn từ thiết bị thử nghiệm. Gửi tin nhắn để xác thực chế độ thiết lập.

Tiếp

Dialogflow