Thông báo Webhook

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

Hiện tại, Roblox hoàn toàn hỗ trợ thông báo webhook cho Discord, Guilded và Slack.Sử dụng webhook với các công cụ bên thứ ba khác mang lại rủi ro không nhận được tất cả các thông báo.

Quy trình làm việc Webhook

Webhooks gửi thông báo hoặc dữ liệu 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ông giống như các API truyền thống, yêu cầu bạn thiết lập ứng dụng khách để gửi yêu cầu đến một máy chủ để nhận dữ liệu, webhooks gửi dữ liệu đến điểm cuối của khách hàng của bạn ngay khi một sự kiện xảy ra.Chúng hữu ích để tự động hóa quy trình làm việc giữa Roblox và ứ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 thời gian thực.

Một 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 yêu cầu đến URL webhook bạn cung cấp.URL webhook sau đó chuyển hướng yêu cầu đến ứng dụng nhận hoặc điểm cuối cùng tùy chỉnh, có thể thực hiện hành động dựa trên dữ liệu bao gồm trong payload webhook.Điều này có thể bao gồm xóa dữ liệu cho GDPR, gửi xác nhận cho người dùng hoặc kích hoạt sự kiện khác.

Kích hoạt được hỗ trợ

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

Đăng ký

Gia hạn đăng ký lại - Khi một người dùng gia hạn đăng ký, một tin nhắn được gửi chứa đăng ký và người gửi.
Gia hạn đăng ký - Khi một người dùng gia hạn đăng ký, một tin nhắn được gửi chứa đăng ký và người đăng ký.
Hoàn trả khách hàng đăng ký - Khi một người dùng nhận được hoàn trả cho đăng ký của họ, một tin nhắn được gửi chứa đăng ký và người đăng ký.
Đăng ký đã mua - Khi một người dùng mua đăng ký, một tin nhắn được gửi chứa đăng ký và người đăng ký.
Hủy đăng ký đã bị huỷ - Khi một người dùng huỷ đăng ký subscription , một tin nhắn được gửi chứa đăng ký và người đăng ký, cũng như lý do được đưa ra để huỷ bỏ.

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

Sự tuân thủ

Quyền yêu cầu xóa dữ liệu - Khi một người dùng gửi yêu cầu xóa dữ liệu dưới Quy định chung về bảo vệ dữ liệu (GDPR).

Thương mại

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

Cài đặt webhook trên Bảng điều khiển Nhà sáng tạo

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

Nếu bạn đang thiết lập webhook và xử lý dữ liệu cá nhân, hãy đảm bảo chúng tuân thủ Quy định chung về bảo vệ dữ liệu (GDPR).

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

Di chuyển đến phần Webhooks của Bảng điều khiển Nhà sáng tạo.
Nhấp vào nút Thêm Webhook .
Hoàn thành các trường cấu hình:
1. URL Webhook - Xác định URL mà bạn muốn nhận thông báo.Để biết thêm thông tin về các yêu cầu, xem Thiết lập URL webhook.
2. Tên - Sử dụng một tên tùy chỉnh để phân biệt cấu hình của bạn với những người khác. Mặc định giá trị là giống như URL Webhook.
3. Bí mật (tùy chọn) - Cung cấp một bí mật nếu bạn muốn xác minh 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.
4. Kích hoạt - Chọn một hoặc nhiều tùy chọn từ danh sách trigger hỗ trợ của sự kiện mà bạn muốn nhận thông báo.
Nhấp vào nút Lưu thay đổi .

Hiện tại, bạn có thể cấu hình tối đa 5 webhook tổng cộng.

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à URL webhook của bạn, miễn là nó đáp ứng các yêu cầu sau:

Nó phải có khả năng truy cập công khai để xử lý yêu cầu.
Nó có thể xử lý các yêu cầu POST.
Nó có thể đáp lại yêu cầu với một 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 yêu cầu POST, nó phải có thể:

Chiết xuất chi tiết cần thiết về thông báo từ cơ thể tin nhắn POST.
Đọc cơ thể của tin nhắn POST với chi tiết chung về thông báo và 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ề cấu trúc của yêu cầu POST để xử lý, hãy xem Payload Schema.

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

Khi thông báo webhook không thể đạt đến URL được chỉ định do các lỗi như không có sẵn điểm cuối, Roblox thử lại gửi tin nhắn đến URL được cấu hình 5 lần bằng kích thước cửa sổ cố định.Nếu thông báo vẫn không được gửi sau 5 lần thử, Roblox ngừng cố gửi thông báo và cho rằng URL không còn hợp lệ.Trong trường hợp 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ể tiếp cận và có thể nhận được 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 được thông báo thành công, hãy xem Thử nghiệm 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 ba công cụ bên thứ ba được hỗ trợ, xem như sau:

Thử nghiệm webhook

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

Điều hướng đến trang cấu hình Webhooks.
Chọn webhook bạn muốn kiểm tra từ danh sách webhook được cấu hình.
Nhấp vào biểu tượng bút cạnh webhook mục tiêu.
Nhấp vào nút Trả lời thử nghiệm .

Hệ thống sau đó 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:

Cấu trúc thông báo mẫu
{
  "NotificationId": "string",
  "EventType": "SampleNotification",
  "EventTime": "2023-12-30T16:24:24.2118874Z",
  "EventPayload": {
    "UserId": 1
  }
}

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

Xác minh bảo mật webhook

Sau khi bạn cấu hình máy chủ để nhận các tải trọng, nó bắt đầu lắng nghe bất kỳ tải trọng nào được gửi đến điểm cuối.Nếu bạn đặt một bí mật khi cấu hình webhook của bạn, Roblox 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 cùng tùy chỉnh và trong phần footer cho các máy chủ bên thứ ba.

Signature format with a secret for custom endpoints
t=<timestamp>,v1=<signature>

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

Signature format without a secret for custom endpoints
t=<timestamp>

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

Chiết xuất giá trị thời gian và chữ ký.Tất cả các chữ ký cho webhook với bí mật chia sẻ cùng một định dạng như một chuỗi CSV với hai giá trị sau đây theo sau các tiền tố:
- t : Thời gian chính xác khi thông báo được gửi.
- v1 : Giá trị ký hiệu được tạo ra bằng cách sử dụng giá trị bí mật được cung cấp bởi cấu hình Bảng điều khiển Nhà sáng tạo.
Tái tạo chuỗi cơ sở của roblox-signature bằng cách ghép nối:
1. Thời gian chạy như một chuỗi.
2. Nhân tính kỳ . .
3. Chuỗi JSON của cơ thể yêu cầu.
Tính toán một mã xác minh tin nhắn dựa trên hash (HMAC) bằng chức năng hash SHA256 bằng cách sử dụng chìa khóa bí mật bạn định nghĩa trong quá trình cài đặt làm chìa khóa và dây chuỗi cơ bản bạn tạo thông qua bước 2 là tin nhắn.Chuyển kết quả sang định dạng Base64 để có được chữ ký mong đợi.
So sánh giá trị chữ ký được chiết xuất với chữ ký mong đợi. Nếu bạn tạo chữ ký chính xác, giá trị nên giống nhau.
(Tùy chọn) Để ngăn chặn các cuộc tấn công lặp lại, một loại cuộc tấn công mạng nơi các kẻ tấn công lấy và gửi lại dữ liệu để có được quyền truy cập không được phép hoặc thực hiện hành động có hại, thì hữu ích khi so sánh giá trị thời gian được chiết xuất với thời gian hiện tại và đảm bảo nó nằm trong giới hạn thời gian hợp lý.Ví dụ, một cửa sổ 10 phút thường là giới hạn thời gian hợp lý.

Cấu trúc dữ liệu Payload

Khi sự kiện mục tiêu của webhook đượ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 yêu cầu chia sẻ cùng một schema bao gồm các trường cố định và biến thiên.Điều này đảm bảo rằng dữ liệu được gửi trong payload được cấu trúc và nhất quán, làm cho việc xử lý và sử dụng dữ liệu của ứng dụng nhận dễ dàng hơn.

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

NotificationId (chuỗi): Một nhận dạng duy nhất cho mỗi thông báo được gửi. Nếu giống nhau NotificationId được nhận hai lần, nó được coi là trùng lặp.
EventType (chuỗi): Chỉ ra loại sự kiện mà thông báo được kích hoạt.
EventTime (chuỗi): Thời gian chạy sự kiện khi nó được kích hoạt.

Các trường tham số biến có tính linh hoạt cho webhook để chứa các loại sự kiện khác nhau, bao gồm:

EventPayload (đối tượng): Bao gồm thông tin cụ thể cho EventType đã kích hoạt webhook.Cấu trúc của EventPayload bảng định dạng thay đổi tùy thuộc vào loại sự kiện.

Ví dụ sau đây cho thấy sơ đồ payload của sự kiện Yêu cầu xóa bỏ bên phải :

Ví dụ sơ đồ cho yêu cầu xóa bỏ bên phải
{
   "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 bất kỳ Thông tin nhận dạng cá nhân (PII) của người dùng, chẳng hạn như ID người dùng của họ, bạn phải xóa thông tin này khi một người dùng gửi yêu cầu tuân thủ các yêu cầu tuân thủ quy định về quyền xóa dữ liệu theo GDPR right to erasure.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 lưu PII trong một kho dữ liệu.Xem Tự động hóa việc xóa yêu cầu xóa dữ liệu để có một ví dụ về cách tạo một bot trong Guilded hoặc Discord sử dụng Mở API đám mây mở 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 áp dụng để 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áy chủ webhook thay vì công cụ bên thứ ba, bạn có thể chiết xuất dữ liệu phải xóa khỏi payload webhook và xây dựng giải pháp tự động hóa riêng của mình.Ví dụ mã sau đây là một ví dụ về một máy chủ có chức năng ngăn chặn các cuộc tấn công lặp lại bằng cách xác minh thời gian chạy và yêu cầu đến từ Roblox:

Extracting PII from Payload
const crypto = require('crypto');
const express = require('express');

const secret = '<your_secret>' // This can be set as an environment variable

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

app.all('/*', function (req, res) {
   console.log('New request recieved');

   // Extract the timestamp and signature from header
   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);

   // Ensure the request came within a 300 second window to prevent replay attacks
   const requestTimestampMs = timestamp * 1000;
   const windowTimeMs = 300 * 1000;
   const oldestTimestampAllowed = Date.now() - windowTimeMs;

   if (requestTimestampMs < oldestTimestampAllowed) {
      return res.status(403).send('Expired Request');
   }

   // Validate signature
   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('Unauthorized Request');
   }

   // Your logic to handle payload
   const payloadBody = req.body;
   const eventType = payloadBody['EventType'];

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

      console.log(`Payload data: UserId=${userId} and GameIds=${gameIds}`);
      // If you store PII in data stores, use the UserId and GameIds to delete the information from data stores.
   }

   return res.json({ message: 'Processed the message successfully' });
});

app.listen(8080, function () {
   console.log('Server started');
});

Trên trang này