Thông báo Webhook | Tài liệu - Trung Tâm Nhà Sáng Tạo Roblox

Thay vì theo dõi tất cả các sự kiện trong trải nghiệm của bạn và yêu cầu từ người dùng, bạn có thể tạo webhook để nhận các thông báo thời gian thực trên một công cụ truyền thông trực tuyến hoặc cổng thông tin của bạn tùy chỉnh có thể nhận các yêu cầu HTTP. Điều này giú

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

Làm việc Webhook

Các Webhook gửi thông báo hoặc dữ liệu thực thời 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ụ gửi tin nhắn thứ ba. Các Webhook gửi dữ liệu đến điểm cuối của

Một khi bạn cài đặt một webhook, mỗi khi một sự kiện mục tiêu xảy ra, Roblox gửi một 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 của bạn hoặc điểm cuối của người dùng, tùy theo dữ

Các hỗ trợ

Roblox hiện đã hỗ trợ các trình phát sự kiện sau đây cho các thông báo:

Subscription Cancelled - Khi một người hủy subscribe, một thông điện sẽ được gửi bao gồm subscribe và subscriber, cũng như lý do cho sự hủy subscribe.
Subscription Purchased - Khi một người mua một kết quả, một thông điện sẽ được gửi chứa kết quả và subscriber.
Subscription Refunded - Khi một người nhận được tiền hoàn trả cho subscrip션 của họ, một thông điện được gửi bao gồm subscripción và subscriber.
Subscription Renewed - Khi một người gia hàng subscribe, một thông điện sẽ được gửi bao gồm subscribe và subscriber.
Subscription Resubscribed - Khi một người subscribe vào một chủ đề, một thông điện sẽ được gửi bao gồm chủ đề và subscriber.
"Quyền bị quên" yêu cầu xóa dữ liệu dưới luật bảo vệ dữ liệu chung ( GDPR ).

Để biết thêm thông tin về các sự kiện subscribe và các trường subscribe, hãy xem tham chiếu Cloud API Subscription.

Tùy chỉnh Webhook trên Creator Dashboard

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

Nếu bạn đang cài đặt webhook và xử lý dữ liệu cá nhân, hãy đảm bảo chúng tuân theo quy định Bảo vệ Dữ liệu Tổng .

Để tạo một webhook:

Navigate to the Webhook section of the Creator Dashboard .
Nhấp vào nút Thêm Webhook .
Hoàn thành các trường cấu hình:
1. URL của Webhook — Định vị URL bạn muốn nhận thông báo và chấp nhận URL Webhook từ các đối tượng thứ ba. Để biết thêm thông tin về các yêu cầu, hãy xem Tùy chỉnh Webhook URL.
2. Tên — Sử dụng tên tùy chỉnh để phân biệt cấu hình của bạn khỏi người khác. Bởi 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 rằng các thông báo bạn nhận đến từ Roblox. Để biết thêm thông tin, hãy xem Xác minh sự an toàn của Webhook.
4. Trình tác hạnh — Chọn một hoặc nhiều lựa chọn từ danh sách các trình tác hạnh được hỗ trợ của sự kiện mà bạn muốn nhận thông báo.
Click the Lưu Thay Đổi button.

Hiện tại, bạn có thể tùy chỉnh tối đa 5 webhook.

Tùy chỉnh URL của Webhook

Bạn có thể cài đặt một cửa hàng HTTP tùy chỉnh như URL của webhook của bạn, miễn là nó đáp ứng các yêu cầu sau đây:

Nó phải được 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 câu trả lời 2XX trong vòng 5 giây.
Nó có thể xử lý các yêu cầu HTTPS.

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

Tiết kiệm chi tiết cần thiết về thông báo từ cơ thể tin nhắn POST.
Đọc thân của thông điệp POST với các chi tiết genéric trên thông báo và các chi tiết liên quan đến kiểu sự kiện trên thông báo.

Để biết thêm thông tin về cấu hình của các yêu cầu POST để xử lý, hãy xem Payload Schema .

Chính sách chuyển khoản

Khi một thông báo webhook không thể kết nối đến URL của bạn do lỗi như không có kết nối đường dẫn, Roblox sẽ thử lại gửi thông báo đến URL cấu hình 5 l

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

Các công cụ của bên thứ ba thường có các yêu cầu riêng của họ cho webhook mà bạn cần phải thiết lập khi cài đặt 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 tham khảo của công cụ hỗ trợ. Đối với ba cô

Thử nghiệm Webhook

Bạn có thể kiểm tra xem liệu webhook bạn đã cấu hình có thể nhận được thông báo thành công trên Creator Dashboard :

Navigate to the trang chủ của Webhook page.
Chọn webhook bạn muốn kiểm tra từ danh sách các webhook được cấu hình.
Nhấp vào biểu tượng bút chì cạnh thẻ web mục tiêu.
Nhấp vào nút Phản hồi thử nghiệm .

Hệ thống sau đó gửi một thông báo trong kiểu SampleNotification, bao gồm User ID của người dùng mà kích hoạt thông báo, như mẫu thông báo sau đây cho thấy:

Tài sản
Body: {
  "NotificationId": "string",
  "EventType": "SampleNotification",
  "EventTime": "2023-12-30T16:24:24.2118874Z", // Loại: Timestamp ISO 8601
  "EventPayload": {
    "UserId": 1 // Loại: Dài
  }
}

Nếu bạn đang tích hợp webhook của mình với một dịch vụ 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 từ webhook của bạn một cách thành công. Nếu bạn cung cấp mộ

Xác minh an toàn Webhook

Một khi bạn cấu hình máy chủ của bạn để nhận các ký sự, nó bắt đầu lắng nghe bất kỳ ký sự nào được gửi đến cổng. Nếu bạn thiết lập một dấu hiệu khi cấ

Signature Format with Secret for Custom Endpoints
"roblox-signature": "t=<timestamp>,v1=<signature>"

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

Signature Format without Secret for Custom Endpoints
"roblox-signature": "t=<timestamp>"

Để xác minh một ký hiệu:

Lấy giá trị thời gian và ký hiệu. Tất cả các ký hiệu cho webhook với các bí mật đều chia sẻ cùng một định dạng như một dòng CSV với các giá trị này theo dấu hiệu:
- t : Giá trị dấu giờ trên khi thời gian thông báo được khoản
- v1 : Giá trị ký hiệu được tạo bằng cách sử dụng giá trị bí mật cung cấp bởi cấu hình Creator Dashboard. Bạn có thể lấy ra hai giá trị này bằng cách sử dụng hàm split() ", mà đơn giản hóa chuỗi dựa trên một delimiter, trong trường hợp này là nhân vật <
Tạo lại dòng chuỗi cơ sở của roblox-signature bằng cách kết hợp:
1. Dấu thời gian như một chuỗi.
2. Nhân vật thời gian . .
3. Chuỗi JSON của cơ thânyêu cầu.
Tính toán một mã mã hóa tin nhắn dựa trên hash (HMAC) bằng cách sử dụng chức năng hash secret bằng cách bạn định nghĩa trong cấu hình như mật mã chính và dòng chuỗi mà bạn tạo thành bước 2 như một dấu hiệu. Chuyển kết quả sang Base64 để nhận dấu hiệu mong đợi.
So sánh giá trị ký hiệu đã lấy được với dấu hiệu mong muốn. Nếu bạn tạo ra ký hiệu một cách chính xác, giá trị nên là như nhau.
(Opcional) Để ngăn chặn các cuộc tấn công lặp lại, một loại cyber attack nơi các kẻ tấn công chặn và gửi lại dữ liệu để nhận quyền truy cập không được phép hoặc thực hiện các hành động xấu xa, nó hữu ích để so sánh giá trị thời gian thực tế lấ

Tải trọng hợp nhất

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 yêu cầu đều chia sẻ cùng một schéa tương tự bao gồm các trường định tĩnh và biến.

Các trường lưu trữ tải xe tải cố định schema có thể giúp duy trì sự coherence trên tất cả các yêu cầu webhook, với các trường sau đây có sẵn:

NotificationId , string : Một ID độc 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 xem như là lặp lại.
EventType , string : Một chuỗi đại diện cho loại sự kiện mà thông báo đã được kích hoạt.
EventTime , timestamp : Một ngày thời gian chính xác để chỉ ra khi sự kiện được kích hoạt.

Các lĩnh vực trong bảng tài nguyên tiêu chuẩn của Webhook có thể chứa các loại sự kiện khác nhau, bao gồm:

EventPayload , object : Đứng chứa thông tin cụ thể cho EventType mà đã kích hoạt webhook. Cấu trúc của trụ cấu 0> EventPayload0> ảnh hưởng dựa trên loại sự kiện.

Ví dụ sau đây cho thấy cấu hình truyền tải của sự kiện Yêu cầu xóa phải :

Example Schema cho Yêu cầu Quyền xóa
Body:{

   "NotificationId": "string",

   "EventType": "RightToErasureRequest",

   "EventTime": "2023-12-30T16:24:24.2118874Z",

   "EventPayload": {

      "UserId": 1, // Loại: Dài

      "GameIds": [ // Loại: Một mat阵 của Longs

         1234, 2345

      ]

   }

}

Xử lý thông báo

Nếu bạn lưu trữ bất kỳ Thông tin có thể xác định cá nhân (TTCN) của ngư

Nếu bạn sử dụng một cổng kết nối tùy chỉnh như làm mô-đun webhook của bạn thay vì một công cụ của bên thứ ba, bạn có thể lấy dữ liệu chủ đề để xóa khỏi webhook payload và xây dựng giải pháp tự động hóa của riêng bạn. Các ví dụ mã sau đây cung cấp một giải pháp

Extracting PII from Payload
const crypto = require('crypto')
const express = require('express');
let app = express();
app.use(express.json());
app.use(express.urlencoded({ extended: true }));
// This is a sample only code
app.all('/*', function (req, res) {
   console.log('-------- New Request Seen -------');
   // 1. Extract the timestamp and signature
   const shared_secret = '<Your secret>' // This can be set as an environment variable
   const hmac = crypto.createHmac('sha256', shared_secret)
   const roblox_signature_header = req.headers['roblox-signature'].split(',')
   // 'roblox-signature' is present in all requests:
   // Timestamp(t) is present in all requests, however signature value(v1) is not set unless a secret is shared during the webhook configuration.
   // Fetch header component at Index 0 -> 't=' and Index 1 -> 'v1='
   const timestamp = roblox_signature_header.find(e => e.startsWith('t=')).substring(2);
   const extracted_signature = roblox_signature_header.find(e => e.startsWith('v1='));
   // 2. Prevent Replay attack: 300 seconds window
   const request_timestamp_ms = timestamp * 1000;
   const window_time_ms = 300 * 1000
   const oldest_timestamp_allowed = Date.now() - window_time_ms;
   if (request_timestamp_ms < oldest_timestamp_allowed) {
      res.status(403).send('Expired Request')
   }
   // 3. Validate Signature
   if (extracted_signature !== undefined) {
      const signature_v1 = extracted_signature.substring(3);
      const message = `${timestamp}.${JSON.stringify(req.body)}`
      const base64_signature = hmac.update(message).digest('base64')
      if (signature_v1 !== base64_signature) {
         res.status(401).send('Unauthorized Request')
      }
   }
   // 4. 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']
      const gameIdString = gameIds.toString()
      console.log(`The payload: UserId=${userId} and GameIds=${gameIdString}`)
      // If you store PII in data stores, use the UserId and GameIds to make a data store call to delete the information.
   }
   // 5. Return Response
   res.json({ message: 'Processed the message Successfully' });
})
app.listen(8080, function () {
   console.log('This is a Sample application')
})