Thông báo webhook

Thay vì theo dõi tất cả các sự kiện trong trò chơi của bạn và các yêu cầu từ người dùng một cách thủ công, bạn có thể thiết lập webhook để nhận thông báo theo thời gian thực trên một công cụ nhắn tin bên thứ ba hoặc điểm cuối tùy chỉnh của bạn có thể nhận các yêu cầu HTTP. Điều này giúp bạn tự động hóa quy trình quản lý thông báo của mình để giảm bớt nỗ lực thủ công trong việc xử lý thông báo.

Quy trình webhook

Webhook gửi thông báo hoặc dữ liệu theo thời gian thực giữa hai ứng dụng hoặc dịch vụ khác nhau, chẳng hạn như Roblox và một công cụ nhắn tin bên thứ ba. Khác với các API truyền thống, yêu cầu bạn thiết lập một ứng dụng khách để gửi yêu cầu đến máy chủ để nhận dữ liệu, webhook gửi dữ liệu đến điểm cuối của bạn ngay khi một sự kiện xảy ra. Chúng rất hữu ích cho việc tự động hóa quy trình làm việc giữa Roblox và các ứng dụng bên thứ ba mà bạn sử dụng để hợp tác với nhóm của mình, vì chúng cho phép chia sẻ và xử lý dữ liệu theo thời gian thực.

Khi bạn thiết lập một webhook, bất cứ khi nào một sự kiện mục tiêu xảy ra, Roblox sẽ gửi một yêu cầu đến URL webhook mà bạn cung cấp. URL webhook sau đó sẽ chuyển tiếp yêu cầu đến ứng dụng nhận của bạn hoặc điểm cuối tùy chỉnh, có thể thực hiện hành động dựa trên dữ liệu được bao gồm trong payload webhook. Điều này có thể bao gồm việc xóa dữ liệu để tuân thủ RTBF, gửi xác nhận cho người dùng hoặc kích hoạt một sự kiện khác.

Các kích hoạt được hỗ trợ

Roblox hiện hỗ trợ các kích hoạt sự kiện sau.

Đăng ký

• Đăng ký lại - Khi một người dùng đăng ký lại một đăng ký, một tin nhắn được gửi chứa thông tin về đăng ký và người đăng ký.
• Đăng ký được gia hạn - Khi một người dùng gia hạn một đăng ký, một tin nhắn được gửi chứa thông tin về đăng ký và người đăng ký.
• Đăng ký được hoàn tiền - Khi một người dùng nhận được hoàn tiền cho đăng ký của họ, một tin nhắn được gửi chứa thông tin về đăng ký và người đăng ký.
• Đăng ký đã mua - Khi một người dùng mua một đăng ký, một tin nhắn được gửi chứa thông tin về đăng ký và người đăng ký.
• Đăng ký đã hủy - Khi một người dùng hủy một đăng ký, một tin nhắn được gửi chứa thông tin về đăng ký và người đăng ký, cũng như lý do được đưa ra cho việc hủy bỏ.

Để biết thêm thông tin về các sự kiện đăng ký và các trường của chúng, hãy xem tài liệu Đăng ký.

Tuân thủ

• Quyền xóa bỏ / Yêu cầu xóa - Khi một người dùng thực hiện quyền của họ để có thông tin cá nhân của họ bị xóa vĩnh viễn theo các quy định về bảo vệ dữ liệu và quyền riêng tư toàn cầu áp dụng. Thông tin thêm có thể được tìm thấy trong RTBF và Creators.

Thương mại

• Đơn hàng sản phẩm thương mại được hoàn tiền - Khi một người dùng đã nhận được hoàn tiền cho đơn hàng sản phẩm thương mại của họ, hoặc đơn hàng đã bị hủy.
• Đơn hàng sản phẩm thương mại đã thanh toán - Khi một người dùng đã thanh toán cho đơn hàng sản phẩm thương mại của họ. Xin lưu ý rằng có thể xảy ra các sự kiện webhook trùng lặp, vì vậy bạn nên loại bỏ các sự kiện trùng lặp bằng cách sử dụng ID đơn hàng thương mại duy nhất.

Cấu hình webhook trên Bảng điều khiển Người sáng tạo

Để nhận thông báo qua webhook, bạn cần cấu hình một webhook đăng ký các sự kiện nhất định để kích hoạt thông báo. Đối với các trò chơi thuộc sở hữu nhóm, chỉ có chủ sở hữu nhóm mới có thể cấu hình và nhận thông báo webhook.

Để thiết lập một webhook:

1. Chọn trải nghiệm của bạn trên Creator Hub.

2. Dưới Cấu hình, chọn Webhooks và nhấp vào Thêm Webhook.

   URL webhook đến từ nhà cung cấp của bạn. Ví dụ, một URL Slack có thể trông như thế này:

   https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX

3. Nhập URL webhook của bạn và một tên.

4. TÙY CHỌN

   Bao gồm một bí mật, giúp đảm bảo rằng các thông báo bạn nhận được đến từ Roblox. Để biết thêm thông tin, xem Xác minh bảo mật webhook.

5. Chọn một hoặc nhiều tùy chọn từ danh sách các kích hoạt được hỗ trợ của các sự kiện mà bạn muốn nhận thông báo.

6. TÙY CHỌN

   Sử dụng nút Kiểm tra Phản hồi để kiểm tra xem dịch vụ của bạn có thể nhận được một yêu cầu mẫu hay không.

7. Nhấp vào Lưu Thay đổi.

Thiết lập URL webhook

Bạn có thể thiết lập một điểm cuối dịch vụ HTTP tùy chỉnh làm URL webhook của bạn, miễn là nó đáp ứng các yêu cầu sau:

• Nó phải có thể truy cập công khai để xử lý các yêu cầu.
• Nó có thể xử lý các yêu cầu POST.
• Nó có thể phản hồi yêu cầu với phản hồi 2XX trong vòng 5 giây.
• Nó có thể xử lý các yêu cầu HTTPS.

Khi điểm cuối của bạn nhận được một yêu cầu POST, nó phải có khả năng:

• Trích xuất các chi tiết cần thiết về thông báo từ nội dung của tin nhắn POST.
• Đọc nội dung của tin nhắn POST với các chi tiết chung về thông báo và các chi tiết cụ thể liên quan đến loại sự kiện trong thông báo.

Để biết thêm thông tin về sơ đồ của các yêu cầu POST cần xử lý, hãy xem Sơ đồ Payload.

Chính sách thử lại khi giao hàng thất bại

Khi một thông báo webhook không thể đến URL mà bạn đã chỉ định do các lỗi như điểm cuối không khả dụng, Roblox sẽ thử gửi lại tin nhắn đến URL đã cấu hình 5 lần bằng cách sử dụng kích thước cửa sổ cố định. Nếu thông báo vẫn không thể được giao sau 5 lần thử, Roblox sẽ ngừng cố gắng gửi thông báo và giả định rằng URL không còn hợp lệ. Trong tình huống này, bạn cần cập nhật cấu hình webhook của mình với một URL mới có thể truy cập và có khả năng nhận thông báo. Để khắc phục sự cố và xác nhận rằng URL webhook của bạn có thể nhận thông báo thành công, hãy xem Kiểm tra webhook.

Yêu cầu bên thứ ba

Các công cụ bên thứ ba thường có các yêu cầu riêng cho webhook mà bạn cần tuân theo khi thiết lập URL webhook của mình. Bạn có thể tìm thấy các yêu cầu này bằng cách tìm kiếm từ khóa "webhook" trên trang hỗ trợ hoặc tài liệu của công cụ mục tiêu. Đối với các công cụ bên thứ ba được hỗ trợ, hãy xem các liên kết sau:

• Trung tâm Trợ giúp Discord
• Tài liệu API Slack

Kiểm tra webhook

Bạn có thể kiểm tra xem webhook mà bạn đã cấu hình có thể nhận thông báo thành công trên Bảng điều khiển Người sáng tạo:

1. Điều hướng đến trang cấu hình Webhooks.
2. Chọn webhook mà bạn muốn kiểm tra từ danh sách các webhook đã cấu hình.
3. Nhấp vào biểu tượng bút chì bên cạnh webhook mục tiêu.
4. Nhấp vào nút Kiểm tra Phản hồi.

Hệ thống sau đó sẽ gửi một sự kiện SampleNotification, bao gồm ID Người dùng của người dùng đã kích hoạt thông báo, như được hiển thị ở đây:

{
  "NotificationId": "string",
  "EventType": "SampleNotification",
  "EventTime": "2023-12-30T16:24:24.2118874Z",
  "EventPayload": {
    "UserId": 1
  }
}

Nếu bạn đang tích hợp webhook của mình với một dịch vụ bên thứ ba, bạn có thể kiểm tra nó bằng cách sử dụng URL bên thứ ba để xác nhận rằng dịch vụ có thể nhận thông báo thành công từ webhook của bạn. Nếu bạn cung cấp một bí mật khi cấu hình webhook, nó cũng sẽ tạo ra một roblox-signature mà bạn có thể sử dụng để kiểm tra logic roblox-signature.

Xác minh bảo mật webhook

Sau khi bạn cấu hình máy chủ của mình để nhận payload, nó bắt đầu lắng nghe bất kỳ payload nào được gửi đến điểm cuối. Nếu bạn đã thiết lập một bí mật khi cấu hình webhook của mình, Roblox sẽ gửi một roblox-signature trong mỗi thông báo webhook để đảm bảo rằng yêu cầu thực sự đến từ Roblox. Chữ ký nằm trong tiêu đề payload cho các điểm cuối tùy chỉnh và trong chân trang cho các máy chủ bên thứ ba.

t=<timestamp>,v1=<signature>

Nếu bạn không thiết lập một bí mật cho webhook của mình, chữ ký chỉ chứa dấu thời gian của khi thông báo được gửi:

t=<timestamp>

Để xác minh một chữ ký:

1. Trích xuất các giá trị dấu thời gian và chữ ký. Tất cả các chữ ký cho webhook có bí mật đều chia sẻ cùng một định dạng dưới dạng chuỗi CSV với hai giá trị này theo sau bởi các tiền tố:

   • t: Dấu thời gian của khi thông báo được gửi.
   • v1: Giá trị chữ ký được tạo ra bằng cách sử dụng bí mật được cung cấp bởi cấu hình Bảng điều khiển Người sáng tạo.

2. Tạo lại chuỗi cơ sở của roblox-signature bằng cách nối:

   1. Dấu thời gian dưới dạng chuỗi.
   2. Ký tự dấu chấm ..
   3. Chuỗi JSON của nội dung yêu cầu.

3. Tính toán mã xác thực dựa trên băm (HMAC) với hàm băm SHA256 bằng cách sử dụng bí mật mà bạn đã định nghĩa trong quá trình cấu hình làm khóa và chuỗi cơ sở mà bạn đã tạo ra qua bước 2 làm thông điệp. Chuyển đổi kết quả sang định dạng Base64 để có được chữ ký mong đợi.

4. So sánh giá trị chữ ký đã trích xuất với chữ ký mong đợi. Nếu bạn đã tạo chữ ký đúng cách, giá trị sẽ giống nhau.

5. TÙY CHỌN

   Để ngăn chặn các cuộc tấn công phát lại, một loại cuộc tấn công mạng mà kẻ tấn công chặn và gửi lại dữ liệu để có được quyền truy cập trái phép hoặc thực hiện các hành động độc hại, sẽ hữu ích khi so sánh giá trị dấu thời gian đã trích xuất với dấu thời gian hiện tại và đảm bảo rằng nó nằm trong một giới hạn thời gian hợp lý. Ví dụ, một khoảng thời gian 10 phút thường là một giới hạn thời gian hợp lý tốt.

Sơ đồ payload

Khi sự kiện mục tiêu của webhook của bạn được kích hoạt, nó gửi một yêu cầu đến URL webhook của bạn, bao gồm thông tin về sự kiện trong payload. Tất cả các payload của các yêu cầu đều chia sẻ cùng một sơ đồ bao gồm các trường cố định và biến. Điều này đảm bảo rằng dữ liệu được truyền trong payload có cấu trúc và nhất quán, giúp cho ứng dụng nhận dễ dàng xử lý và sử dụng dữ liệu.

Các trường sơ đồ payload cố định có thể giúp duy trì tính nhất quán trên tất cả các yêu cầu webhook, với các trường sau đây có sẵn:

1. NotificationId (chuỗi): Một định danh duy nhất cho mỗi thông báo được gửi. Nếu cùng một NotificationId được nhận hai lần, nó được coi là một bản sao.
2. EventType (chuỗi): Chỉ ra loại sự kiện mà thông báo được kích hoạt.
3. EventTime (chuỗi): Dấu thời gian của khi sự kiện được kích hoạt.

Các trường sơ đồ payload biến cung cấp tính linh hoạt cho các webhook để đáp ứng các loại sự kiện khác nhau, bao gồm:

1. EventPayload (đối tượng): Chứa thông tin cụ thể cho EventType đã kích hoạt webhook. Cấu trúc của sơ đồ EventPayload thay đổi dựa trên loại sự kiện.

Ví dụ sau đây cho thấy sơ đồ payload của sự kiện Yêu cầu Quyền Xóa Bỏ:

{
   "NotificationId": "string",
   "EventType": "RightToErasureRequest",
   "EventTime": "2023-12-30T16:24:24.2118874Z",
   "EventPayload": {
      "UserId": 1,
      "GameIds": [
         1234, 2345
      ]
   }
}

Xử lý thông báo

Nếu bạn lưu trữ bất kỳ Thông tin Cá nhân (PII) nào của người dùng, chẳng hạn như ID Người dùng của họ, bạn nên đánh giá yêu cầu trong bối cảnh nghĩa vụ pháp lý của bạn. Thông tin thêm có thể được tìm thấy trong RTBF và Creators. Bạn có thể tạo một bot để xử lý thông báo webhook và giúp tự động hóa việc xóa dữ liệu, miễn là bạn đang lưu trữ PII trong một kho dữ liệu. Xem Tự động hóa Yêu cầu Xóa Bỏ để biết ví dụ về cách tạo một bot trong Discord sử dụng Open Cloud API cho kho dữ liệu để xóa dữ liệu PII như một giải pháp tự động hóa. Ví dụ này có thể được điều chỉnh để xử lý các thông báo khác, chẳng hạn như sự kiện đăng ký.

Nếu bạn sử dụng một điểm cuối tùy chỉnh làm máy chủ webhook của mình thay vì một công cụ bên thứ ba, bạn có thể trích xuất dữ liệu cần xóa từ payload webhook và xây dựng giải pháp tự động hóa của riêng bạn. Mẫu mã sau đây là một ví dụ về một máy chủ có biện pháp ngăn chặn các cuộc tấn công phát lại bằng cách xác minh dấu thời gian và rằng yêu cầu đến từ Roblox:

const crypto = require('crypto');
const express = require('express');

const secret = '<your_secret>' // Điều này có thể được thiết lập như một biến môi trường

let app = express();
app.use(express.json());

app.all('/*', function (req, res) {
   console.log('Yêu cầu mới đã nhận');

   // Trích xuất dấu thời gian và chữ ký từ tiêu đề
   const signatureHeader = req.headers['roblox-signature'].split(',');
   const timestamp = signatureHeader.find(e => e.startsWith('t=')).substring(2);
   const signature = signatureHeader.find(e => e.startsWith('v1=')).substring(3);

   // Đảm bảo yêu cầu đến trong khoảng thời gian 300 giây để ngăn chặn các cuộc tấn công phát lại
   const requestTimestampMs = timestamp * 1000;
   const windowTimeMs = 300 * 1000;
   const oldestTimestampAllowed = Date.now() - windowTimeMs;

   if (requestTimestampMs < oldestTimestampAllowed) {
      return res.status(403).send('Yêu cầu đã hết hạn');
   }

   // Xác thực chữ ký
   const message = `${timestamp}.${JSON.stringify(req.body)}`;
   const hmac = crypto.createHmac('sha256', secret);
   const calculatedSignature = hmac.update(message).digest('base64');

   if (signature !== calculatedSignature) {
      return res.status(401).send('Yêu cầu không hợp lệ');
   }

   // Logic của bạn để xử lý payload
   const payloadBody = req.body;
   const eventType = payloadBody['EventType'];

   if (eventType === 'RightToErasureRequest'){
      const userId = payloadBody['EventPayload']['UserId'];
      const gameIds = payloadBody['EventPayload']['GameIds'];

      console.log(`Dữ liệu payload: UserId=${userId} và GameIds=${gameIds}`);
      // Nếu bạn lưu trữ PII trong kho dữ liệu, hãy sử dụng UserId và GameIds để xóa thông tin từ kho dữ liệu.
   }

   return res.json({ message: 'Đã xử lý tin nhắn thành công' });
});

app.listen(8080, function () {
   console.log('Máy chủ đã khởi động');
});