Webhook là một lệnh gọi lại HTTPS do đối tác tạo. Lệnh gọi lại này chỉ định cách nhân viên hỗ trợ của bạn phản hồi tin nhắn và sự kiện. 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ủa mình ở 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 nhân viên hỗ trợ mà bạn duy trì. Nếu nhân viên hỗ trợ của bạn có hành vi tương tự hoặc nếu bạn chỉ có một nhân viên hỗ trợ, hãy sử dụng webhook của đố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 điều hành nhiều nhân viên hỗ trợ có hành vi riêng biệt, bạn có thể đặt một webhook khác nhau cho từng nhân viên hỗ trợ.
Nếu bạn đã định cấu hình cả webhook của đối tác và webhook của nhân viên hỗ trợ, thì webhook của nhân viên hỗ trợ sẽ được ưu tiên so với webhook cụ thể, còn webhook của đố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 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ể chuyển đến một webhook khác, hãy đặt webhook của nhân viên hỗ trợ.
- Mở Business Communications Developer Console và đă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 của bạn bắt đầu bằng "https://".
- Ghi lại giá trị
clientTokencủa bạn. Bạn cần mã này để xác minh rằng các tin nhắn bạn nhận được đến từ Google. Hãy định cấu hình webhook của bạn để chấp nhận yêu cầu
POSTbằng thông sốclientTokenđược chỉ định và gửi một phản hồi200 OKvới giá trị văn bản thuần tuý của thông sốsecretlàm nội dung phản hồi.Ví dụ: nếu webhook của bạn nhận được yêu cầu
POSTcó nội dung cơ thể sau đây{ "clientToken":"SJENCPGJESMGUFPY", "secret":"1234567890" }thì webhook của bạn phải xác nhận giá trị
clientTokenvà nếuclientTokenchính xác, hãy trả về phản hồi200 OK, trong đó có1234567890là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 Bảng điều khiển dành cho nhà phát triển, 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ừ bất kỳ người gửi nào, bạn nên 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 tin nhắn mà bạn nhận được, hãy làm theo các bước sau:
- Trích xuất tiêu đề
X-Goog-Signaturecủa thư. Đây là một bản sao đã băm, được mã hoá base64 của tải trọng nội dung thư. - Giải mã cơ sở 64 của tải trọng RBM trong phần tử
message.bodycủa yêu cầu. - Sử dụng mã thông báo máy khách của webhook (mà bạn chỉ định khi thiết lập webhook) làm khoá, tạo một HMAC SHA512 cho các byte của tải trọng thông báo được giải mã base-64 và mã hoá base64.
- So sánh hàm băm
X-Goog-Signaturevới hàm băm mà bạn đã tạo.- Nếu các hàm băm khớp với nhau, thì bạn đã xác nhận rằng Google đã gửi thư.
Nếu các hàm băm không khớp, hãy kiểm tra quy trình băm trên một thông báo đã biết là hợp lệ.
Nếu quy trình băm của bạn đang hoạt động chính xác và bạn nhận được thư mà bạn cho rằng đã bị gửi cho bạn theo 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ỳ nội dung nào không phải là 200 OK từ một webhook được coi là một lỗi phân phối.
Nhà phát triển phải lưu ý rằng việc gửi tin nhắn ở tốc độ cao sẽ tạo ra thông báo webhook ở tốc độ cao và phải thiết kế mã để đảm bảo họ có thể xem thông báo ở tốc độ dự kiến. Điều quan trọng là các nhà phát triển phải cân nhắc các tình huống có thể gây ra phản hồi lỗ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. Các yếu tố cần xem xét bao gồm:
- Đảm bảo bạn định cấu hình các biện pháp bảo vệ chống DDoS để xử lý tỷ lệ thông báo webhook dự kiến.
- Đảm bảo 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.
Hành vi khi không thể giao hàng
RBM sử dụng cơ chế thời gian đợi và thử lại khi nhận được một phản hồi không phải là 200 OK từ một cuộc 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. Hoạt động gỡ bỏ sẽ tiếp tục trong 7 ngày, sau đó thông báo sẽ bị loại bỏ.
Ngụ ý của webhook ở cấp nhân viên hỗ trợ
RBM xếp tin nhắn cho đối tác vào một hàng đợi. Khi đối tác sử dụng webhook ở cấp độ tác nhân, bạn cần lưu ý rằng lỗi của một webhook sẽ ảnh hưởng đến việc phân phối đến các webhook khác. Webhook thuộc về các tác nhân khác sẽ được gọi trong thời gian đợi của một thông báo không thành công nhưng khi các thông báo không thành công sẽ xếp hàng để thử lại, tốc độ 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 và mã này sao cho phù hợp, nhất có thể, chấp nhận thông báo và đưa chúng vào hàng đợi xử lý nhằm giảm thiểu khả năng 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 của bạn. Gửi tin nhắn để xác thực chế độ thiết lập của bạn.