Nhà Sáng Tạo

Thông báo webhook

*Nội dung này được dịch bằng AI (Beta) và có thể có lỗi. Để xem trang này bằng tiếng Anh, hãy nhấp vào đây.

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 thời gian thực trên một công cụ nhắn tin bên thứ ba hoặc điểm kết thúc 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 làm việc với webhook

Webhook 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ư API truyền thống, yêu cầu bạn phải thiết lập một ứng dụng khách để gửi yêu cầu tới một máy chủ để nhận dữ liệu, webhook gửi dữ liệu đến điểm kết thúc khách 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à các ứng dụng bên thứ ba mà bạn sử dụng để cộng tác với nhóm của bạn, vì chúng cho phép chia sẻ và xử lý dữ liệu 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 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 kết thúc 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 việc xóa dữ liệu cho GDPR, 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 tại 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 sẽ được gửi chứa thông tin về đăng ký và người đăng ký.
  • Đăng ký gia hạn - Khi một người dùng gia hạn một đăng ký, một tin nhắn sẽ được gửi chứa thông tin về đăng ký và người đăng ký.
  • Đăng ký 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 sẽ đượ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 sẽ đượ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 sẽ được gửi chứa thông tin về đăng ký và người đăng ký, cũng như lý do đã cho 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 Đăng ký tham khảo.

Tuân thủ

Thương mại

  • Đơn đặt 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 đặt hàng sản phẩm thương mại của họ, hoặc đơn hàng đã bị hủy.
  • Đơn đặt 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 đặt hàng sản phẩm thương mại của họ. Xin lưu ý rằng có thể xảy ra 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 Creator

Để nhận thông báo qua webhook, bạn cần cấu hình một webhook để đăng ký cho một số sự kiện cho việc kích hoạt thông báo. Đối với các trò chơi thuộc sở hữu của nhóm, chỉ có những 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 Webhook 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 của Slack có thể trông giố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, hãy 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 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 với yêu cầu bằng 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ử nghiệm lại khi giao hàng thất bại

Khi một thông báo webhook không thể đến được URL mà bạn đã chỉ định do các lỗi như không khả dụng của điểm cuối, 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 được gửi đi 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ể tiếp cận 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ành công các thông báo, hãy xem Kiểm tra webhook.

Các 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 thủ khi thiết lập URL webhook của bạn. Bạn có thể tìm thấy những 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ợ, xem các liên kết sau:

Kiểm tra webhook

Bạn có thể kiểm tra xem webhook 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 Creator:

  1. Điều hướng đến trang cấu hình Webhooks.
  2. Chọn webhook 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 đó 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ư sau:

Sơ đồ SampleNotification
{

  "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 của 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 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 các 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 đã đặt 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.

Định dạng chữ ký với bí mật cho các điểm cuối tùy chỉnh
t=<timestamp>,v1=<signature>

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

Định dạng chữ ký không có bí mật cho các điểm cuối tùy chỉnh
t=<timestamp>

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

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

    • t: Thời gian 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 Creator.

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

    1. Thời gian dưới dạng chuỗi.
    2. Ký tự 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 tin nhắn dựa trên hash (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 cấu hình làm khóa và chuỗi cơ bản mà bạn tạo ra qua bước 2 làm tin nhắn. Chuyển đổi kết quả thành đị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ý chính xác, 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 trong đó các kẻ tấn công chiếm đoạt 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, điều thích hợp là so sánh giá trị timestamp đã trích xuất với timestamp hiện tại và đảm bảo rằng nó nằm trong một khoảng thời gian hợp lý. Ví dụ, một khoảng thời gian 10 phút thường là một khoảng 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ó sẽ 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 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 tải trong payload được cấu trúc và nhất quán, khiến cho việc xử lý và sử dụng dữ liệu trở nên dễ dàng hơn cho ứng dụng nhận.

Các trường sơ đồ payload cố định có thể giúp duy trì tính nhất quán trong tất cả các yêu cầu webhook, với các trường sau 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, được coi là một bản sao.
  2. EventType (chuỗi): Chỉ định loại sự kiện cho mà thông báo được kích hoạt.
  3. EventTime (chuỗi): Thời gian khi sự kiện được kích hoạt.

Các trường sơ đồ payload biến cung cấp sự linh hoạt cho webhook để phù hợp với nhiều 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 hiển thị sơ đồ payload của sự kiện Yêu cầu Quyền xóa:

Sơ đồ ví dụ cho yêu cầu Quyền xóa
{

   "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 của bạn, 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 như vậy để tuân thủ các yêu cầu tuân thủ quyền xóa GDPR. Bạn có thể tạo một bot để xử lý các 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 Việc Xóa Yêu cầu Quyền xóa để biết mộ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 kết thúc tùy chỉnh làm máy chủ webhook 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 là một ví dụ về một máy chủ có ngăn chặn các cuộc tấn công phát lại bằng cách xác minh timestamp và việc yêu cầu đến từ Roblox:

Trích xuất PII từ Payload
const crypto = require('crypto');

const express = require('express');



const secret = '<your_secret>' // Điều này có thể được đặt làm 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 được nhận');



   // Trích xuất timestamp 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 được ủy quyền');

   }



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

});
©2026 Roblox Corporation. Roblox, logo Roblox và Powering Imagination là các nhãn hiệu đã đăng ký và chưa đăng ký của chúng tôi tại Hoa Kỳ và các quốc gia khác.
Điều Khoản·Quyền Riêng Tư·Khả Năng Truy Cập·Hỗ Trợ
Tiếng Việt