Webhook là một URL do đối tác chỉ định, nơi nền tảng RCS for Business đăng tin nhắn và sự kiện. URL này hoạt động như một điểm cuối nhận các yêu cầu HTTPS POST 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ể trô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 của đối tác áp dụng cho mọi nhân viên hỗ trợ mà bạn duy trì. Nếu các 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 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 trên nhân viên hỗ trợ cụ thể của mình, trong khi webhook của đối tác áp dụng cho mọi nhân viên hỗ trợ không có webhook riêng.
Định cấu hình webhook của 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 webhook của 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 RCS for Business.
- Nhấp vào nhân viên hỗ trợ của bạn.
- Nhấp vào Các công cụ 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 giá trị này để xác minh rằng tin nhắn bạn nhận được là của Google. Định cấu hình webhook để chấp nhận yêu cầu
POSTcó tham sốclientTokenđược chỉ định và gửi phản hồi200 OKcó giá trị văn bản thuần tuý của tham 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 sau{ "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 OKcó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 Developer Console (Bảng điều khiển dành cho nhà phát triển), hãy nhấp vào Xác minh. Khi RCS for Business 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, nên bạn cầ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 tin nhắn. Đây là một bản sao được mã hoá base64 và băm của tải trọng nội dung thư. - Giải mã base-64 tải trọng RCS for Business trong phần tử
message.bodycủa yêu cầu. - Sử dụng mã thông báo ứng dụng của webhook (mà bạn đã chỉ định khi thiết lập webhook) làm khoá, tạo HMAC SHA512 của các byte trong tải trọng tin nhắn đã giải mã base-64 và mã hoá base64 kết quả.
- 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 nhau, thì 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 nhau, hãy kiểm tra quy trình băm trên một tin nhắn đã biết là tốt.
Nếu quy trình băm của bạn hoạt động chính xác và bạn nhận được một tin nhắn mà bạn cho rằng đã được gửi đến 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ừ một webhook đều được coi là lỗi gửi.
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. 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 lỗi, bao gồm cả phản hồi 500 từ vùng chứa trên 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ệ 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.
Điều quan trọng là 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:
Hành vi khi gửi không thành công
Nếu webhook của bạn trả về bất kỳ trạng thái nào khác ngoài 200 OK, thì nền tảng RCS for Business sẽ sử dụng cơ chế lùi và thử lại để gửi lại dữ liệu. Điều này có nghĩa là hệ thống sẽ tăng dần độ trễ giữa mỗi lần thử gửi, cuối cùng đạt đến tần suất tối đa là một lần thử lại cứ 10 phút cho mỗi tin nhắn đang chờ xử lý. Chu kỳ thử lại tiếp tục trong 7 ngày, sau đó tin nhắn sẽ bị xoá vĩnh viễn.
Ý nghĩa của webhook ở cấp nhân viên hỗ trợ
RCS for Business xếp hàng tin nhắn cho một đối tác trên một hàng đợi. Tất cả nhân viên hỗ trợ trong một tài khoản đối tác đều dùng chung một hàng đợi. Do đó, lỗi trong một webhook có thể chặn toàn bộ hàng đợi, ngăn các sự kiện của người dùng cho tất cả nhân viên hỗ trợ tiếp cận đối tác.
Một số tin nhắn chưa được xác nhận có thể gây ra sự tăng đột biến lớn về các sự kiện thử lại. Ví dụ: nếu một nhân viên hỗ trợ không xác nhận 1.600 biên nhận gửi và tần suất thử lại đạt đến giới hạn 10 phút, thì có thể tạo ra khoảng 230.000 lỗi tiềm ẩn mỗi ngày:
1.600 tin nhắn × 6 lần thử lại mỗi giờ × 24 giờ mỗi ngày = khoảng 230.000 lỗi mỗi ngày
Số lượng thử lại này có thể chặn hàng đợi Pub/Sub dùng chung và gây ra sự chậm trễ đáng kể trong việc nhận các sự kiện của người dùng cho tất cả chiến dịch của một đối tác.
Các phương pháp hay nhất
Để đảm bảo độ tin cậy của lưu lượng truy cập sản xuất và tránh các trình chặn hàng đợi, hãy làm theo các phương pháp hay nhất sau:
- Trả về 200 OK ngay lập tức: Webhook phải nhận tin nhắn,
lưu trữ tin nhắn đó trong một hàng đợi cục bộ và trả về phản hồi
200 OKtrong vòng 5 giây. - Tách rời quá trình xử lý: Sử dụng các trình chạy nền riêng biệt để xử lý logic tin nhắn từ hàng đợi cục bộ.
- Giám sát nhân viên hỗ trợ thử nghiệm: Coi nhân viên hỗ trợ phát triển như nhân viên hỗ trợ sản xuất, vì họ cũng có thể chặn hàng đợi đối tác dùng chung nếu không thành công.
- Tài khoản riêng biệt để thử nghiệm: Tốt nhất là sử dụng một tài khoản nhà phát triển cho nhân viên hỗ trợ sản xuất và một tài khoản nhà phát triển riêng biệt cho nhân viên hỗ trợ thử nghiệm.
- Xác minh lưu lượng truy cập của Google: Sử dụng DNS ngược hoặc tiêu đề
X-Goog-Signaturethay vì danh sách cho phép IP cố định, vì Google sử dụng IP anycast động. Để biết thêm thông tin về quy trình xác minh thủ công và xác định dải IP của Google, hãy xem tài liệu Xác minh yêu cầu của Google và cụ thể là tệp JSON cho trình tìm nạp do người dùng kích hoạt và trình tìm nạp do người dùng Google kích hoạt.
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ừ các thiết bị thử nghiệm. Gửi một tin nhắn để xác thực chế độ thiết lập.