การแจ้งเตือน Webhook

แทนที่จะติดตามเหตุการณ์ทั้งหมดในเกมของคุณและคำขอจากผู้ใช้ด้วยตนเอง คุณสามารถตั้งค่า webhook เพื่อรับการแจ้งเตือนแบบเรียลไทม์บนเครื่องมือการส่งข้อความของบุคคลที่สามหรือจุดสิ้นสุดที่กำหนดเองของคุณที่สามารถรับคำขอ HTTP ได้ สิ่งนี้ช่วยให้คุณทำให้การจัดการการแจ้งเตือนของคุณเป็นไปโดยอัตโนมัติเพื่อลดความพยายามในการจัดการการแจ้งเตือนด้วยตนเอง

กระบวนการทำงานของ Webhook

Webhook ส่งการแจ้งเตือนหรือข้อมูลแบบเรียลไทม์ระหว่างแอปพลิเคชันหรือบริการที่แตกต่างกันสองตัว เช่น Roblox และเครื่องมือการส่งข้อความของบุคคลที่สาม แตกต่างจาก API แบบดั้งเดิมซึ่งต้องการให้คุณตั้งค่าแอปพลิเคชันไคลเอนต์เพื่อส่งคำขอไปยังเซิร์ฟเวอร์เพื่อรับข้อมูล Webhook จะส่งข้อมูลไปยังจุดสิ้นสุดของไคลเอนต์ของคุณทันทีที่เกิดเหตุการณ์ขึ้น ซึ่งมีประโยชน์สำหรับการทำให้กระบวนการทำงานระหว่าง Roblox และแอปพลิเคชันของบุคคลที่สามที่คุณใช้ในการทำงานร่วมกับทีมของคุณเป็นไปโดยอัตโนมัติ เนื่องจากช่วยให้สามารถแชร์และประมวลผลข้อมูลแบบเรียลไทม์ได้

เมื่อคุณตั้งค่า webhook แล้ว ทุกครั้งที่เกิดเหตุการณ์เป้าหมาย Roblox จะส่งคำขอไปยัง URL ของ webhook ที่คุณให้ไว้ จากนั้น URL ของ webhook จะเปลี่ยนเส้นทางคำขอไปยังแอปพลิเคชันที่คุณรับหรือจุดสิ้นสุดที่กำหนดเอง ซึ่งสามารถดำเนินการตามข้อมูลที่รวมอยู่ใน payload ของ webhook ได้ ซึ่งอาจรวมถึงการลบข้อมูลเพื่อให้เป็นไปตาม RTBF การส่งการยืนยันไปยังผู้ใช้ หรือการกระตุ้นเหตุการณ์อื่น

ทริกเกอร์ที่รองรับ

Roblox รองรับทริกเกอร์เหตุการณ์ต่อไปนี้ในปัจจุบัน

การสมัครสมาชิก

• การสมัครสมาชิกใหม่ - เมื่อผู้ใช้สมัครสมาชิกใหม่ ข้อความจะถูกส่งที่มีข้อมูลการสมัครสมาชิกและผู้สมัครสมาชิก
• การสมัครสมาชิกต่ออายุ - เมื่อผู้ใช้ต่ออายุการสมัครสมาชิก ข้อความจะถูกส่งที่มีข้อมูลการสมัครสมาชิกและผู้สมัครสมาชิก
• การคืนเงินการสมัครสมาชิก - เมื่อผู้ใช้ได้รับเงินคืนสำหรับการสมัครสมาชิก ข้อความจะถูกส่งที่มีข้อมูลการสมัครสมาชิกและผู้สมัครสมาชิก
• การซื้อการสมัครสมาชิก - เมื่อผู้ใช้ซื้อการสมัครสมาชิก ข้อความจะถูกส่งที่มีข้อมูลการสมัครสมาชิกและผู้สมัครสมาชิก
• การยกเลิกการสมัครสมาชิก - เมื่อผู้ใช้ยกเลิก การสมัครสมาชิก ข้อความจะถูกส่งที่มีข้อมูลการสมัครสมาชิกและผู้สมัครสมาชิก รวมถึงเหตุผลที่ให้สำหรับการยกเลิก

สำหรับข้อมูลเพิ่มเติมเกี่ยวกับเหตุการณ์การสมัครสมาชิกและฟิลด์ของพวกเขา โปรดดูที่ การสมัครสมาชิก อ้างอิง

การปฏิบัติตาม

• สิทธิในการลบข้อมูล / คำขอลบข้อมูล - เมื่อผู้ใช้ใช้สิทธิในการลบข้อมูลส่วนบุคคลของตนอย่างถาวรตามกฎระเบียบการปกป้องข้อมูลและความเป็นส่วนตัวทั่วโลกที่เกี่ยวข้อง ข้อมูลเพิ่มเติมสามารถพบได้ใน RTBF และผู้สร้าง

การค้า

• การคืนเงินคำสั่งซื้อผลิตภัณฑ์การค้า - เมื่อผู้ใช้ได้รับเงินคืนสำหรับคำสั่งซื้อผลิตภัณฑ์การค้า หรือคำสั่งซื้อนั้นถูกยกเลิก
• การชำระเงินคำสั่งซื้อผลิตภัณฑ์การค้า - เมื่อผู้ใช้ชำระเงินสำหรับคำสั่งซื้อผลิตภัณฑ์การค้า โปรดทราบว่ามีความเป็นไปได้ที่จะเกิดเหตุการณ์ webhook ซ้ำ ดังนั้นคุณควรลบเหตุการณ์ที่ซ้ำกันโดยใช้หมายเลขคำสั่งซื้อการค้าที่ไม่ซ้ำกัน

ตั้งค่า webhook บน Creator Dashboard

เพื่อรับการแจ้งเตือนผ่าน webhook คุณต้องกำหนดค่า webhook ที่สมัครสมาชิกกับเหตุการณ์บางอย่างเพื่อกระตุ้นการแจ้งเตือน สำหรับเกมที่เป็นเจ้าของกลุ่ม เจ้าของกลุ่มเท่านั้นที่สามารถกำหนดค่าและรับการแจ้งเตือน webhook ได้

ในการตั้งค่า webhook:

1. เลือกประสบการณ์ของคุณใน Creator Hub.

2. ภายใต้ กำหนดค่า ให้เลือก Webhook และคลิก เพิ่ม Webhook.

   URL ของ webhook มาจากผู้ให้บริการของคุณ ตัวอย่างเช่น URL ของ Slack อาจมีลักษณะดังนี้:

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

3. ป้อน URL ของ webhook และชื่อ

4. OPTIONAL

   รวมความลับ ซึ่งช่วยให้แน่ใจว่าการแจ้งเตือนที่คุณได้รับมาจาก Roblox สำหรับข้อมูลเพิ่มเติม โปรดดูที่ ตรวจสอบความปลอดภัยของ webhook.

5. เลือกหนึ่งตัวเลือกหรือมากกว่าจากรายการ ทริกเกอร์ที่รองรับ ของเหตุการณ์ที่คุณต้องการรับการแจ้งเตือน

6. OPTIONAL

   ใช้ปุ่ม ทดสอบการตอบกลับ เพื่อตรวจสอบว่าบริการของคุณสามารถรับคำขอตัวอย่างได้หรือไม่

7. คลิก บันทึกการเปลี่ยนแปลง.

ตั้งค่า URL ของ webhook

คุณสามารถตั้งค่าจุดสิ้นสุดบริการ HTTP ที่กำหนดเองเป็น URL ของ webhook ของคุณ โดยต้องปฏิบัติตามข้อกำหนดต่อไปนี้:

• ต้องสามารถเข้าถึงได้สาธารณะเพื่อจัดการคำขอ
• ต้องสามารถจัดการคำขอ POST ได้
• ต้องสามารถตอบสนองต่อคำขอด้วยการตอบสนอง 2XX ภายใน 5 วินาที
• ต้องสามารถจัดการคำขอ HTTPS ได้

เมื่อจุดสิ้นสุดของคุณได้รับคำขอ POST จะต้องสามารถ:

• ดึงรายละเอียดที่จำเป็นเกี่ยวกับการแจ้งเตือนจากเนื้อหาของข้อความ POST
• อ่านเนื้อหาของข้อความ POST ที่มีรายละเอียดทั่วไปเกี่ยวกับการแจ้งเตือนและรายละเอียดเฉพาะที่เกี่ยวข้องกับประเภทเหตุการณ์ในการแจ้งเตือน

สำหรับข้อมูลเพิ่มเติมเกี่ยวกับสคีมาของคำขอ POST ที่ต้องจัดการ โปรดดูที่ Payload Schema.

นโยบายการลองส่งซ้ำเมื่อการจัดส่งล้มเหลว

เมื่อการแจ้งเตือน webhook ไม่สามารถไปถึง URL ที่คุณกำหนดได้เนื่องจากข้อผิดพลาด เช่น จุดสิ้นสุดไม่สามารถใช้งานได้ Roblox จะลองส่งข้อความไปยัง URL ที่กำหนดไว้ 5 ครั้งโดยใช้ขนาดหน้าต่างคงที่ หากการแจ้งเตือนยังไม่สามารถส่งได้หลังจาก 5 ครั้ง Roblox จะหยุดพยายามส่งการแจ้งเตือนและถือว่ URL นั้นไม่ถูกต้องอีกต่อไป ในกรณีนี้ คุณต้องอัปเดตการกำหนดค่า webhook ของคุณด้วย URL ใหม่ที่สามารถเข้าถึงได้และสามารถรับการแจ้งเตือนได้ เพื่อแก้ไขปัญหาและยืนยันว่า URL ของ webhook ของคุณสามารถรับการแจ้งเตือนได้สำเร็จ โปรดดูที่ ทดสอบ webhook.

ข้อกำหนดของบุคคลที่สาม

เครื่องมือของบุคคลที่สามมักมีข้อกำหนดของตนเองสำหรับ webhook ที่คุณต้องปฏิบัติตามเมื่อกำหนดค่า URL ของ webhook ของคุณ คุณสามารถค้นหาข้อกำหนดเหล่านี้ได้โดยการค้นหาคำว่า "webhook" บนเว็บไซต์สนับสนุนหรือเอกสารของเครื่องมือเป้าหมาย สำหรับเครื่องมือของบุคคลที่สามที่รองรับ โปรดดูที่ต่อไปนี้:

• ศูนย์ช่วยเหลือ Discord
• เอกสาร API ของ Slack

ทดสอบ webhook

คุณสามารถทดสอบว่า webhook ที่คุณกำหนดค่าไว้สามารถรับการแจ้งเตือนได้สำเร็จบน Creator Dashboard:

1. ไปที่หน้าการกำหนดค่า Webhook.
2. เลือก webhook ที่คุณต้องการทดสอบจากรายการ webhook ที่กำหนดค่าไว้
3. คลิกที่ไอคอนดินสอถัดจาก webhook เป้าหมาย
4. คลิกปุ่ม ทดสอบการตอบกลับ.

ระบบจะส่งเหตุการณ์ SampleNotification ซึ่งรวมถึง User ID ของผู้ใช้ที่กระตุ้นการแจ้งเตือน ดังที่แสดงด้านล่าง:

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

หากคุณกำลังรวม webhook ของคุณกับบริการของบุคคลที่สาม คุณสามารถทดสอบโดยใช้ URL ของบุคคลที่สามเพื่อยืนยันว่าบริการสามารถรับการแจ้งเตือนจาก webhook ของคุณได้สำเร็จ หากคุณให้ความลับเมื่อกำหนดค่า webhook มันจะสร้าง roblox-signature ที่คุณสามารถใช้เพื่อตรวจสอบตรรกะ roblox-signature ได้

ตรวจสอบความปลอดภัยของ webhook

หลังจากที่คุณกำหนดค่าเซิร์ฟเวอร์ของคุณเพื่อรับ payload มันจะเริ่มฟังสำหรับ payload ใด ๆ ที่ส่งไปยังจุดสิ้นสุด หากคุณตั้งค่าความลับเมื่อกำหนดค่า webhook ของคุณ Roblox จะส่ง roblox-signature ในแต่ละการแจ้งเตือน webhook เพื่อให้แน่ใจว่าคำขอจริงมาจาก Roblox ลายเซ็นจะอยู่ในส่วนหัวของ payload สำหรับจุดสิ้นสุดที่กำหนดเองและในส่วนท้ายสำหรับเซิร์ฟเวอร์ของบุคคลที่สาม

t=<timestamp>,v1=<signature>

หากคุณไม่ได้ตั้งค่าความลับสำหรับ webhook ของคุณ ลายเซ็นจะมีเพียงเวลาที่ส่งการแจ้งเตือน:

t=<timestamp>

ในการตรวจสอบลายเซ็น:

1. ดึงค่า timestamp และ signature ออกมา ลายเซ็นทั้งหมดสำหรับ webhook ที่มีความลับจะแบ่งปันรูปแบบเดียวกันเป็นสตริง CSV โดยมีสองค่าที่ตามด้วยพรีฟิก:

   • t: เวลาที่ส่งการแจ้งเตือน
   • v1: ค่าลายเซ็นที่สร้างขึ้นโดยใช้ความลับที่ให้ไว้ในการกำหนดค่าของ Creator Dashboard

2. สร้างสตริงฐานของ roblox-signature โดยการเชื่อมต่อ:

   1. เวลาที่ส่งเป็นสตริง
   2. ตัวอักษรจุด .
   3. สตริง JSON ของเนื้อหาคำขอ

3. คำนวณรหัสยืนยันข้อความแบบ HMAC (HMAC) โดยใช้ฟังก์ชันแฮช SHA256 โดยใช้ความลับที่คุณกำหนดไว้ในระหว่างการกำหนดค่าเป็นกุญแจและสตริงฐานที่คุณสร้างขึ้นในขั้นตอนที่ 2 เป็นข้อความ แปลงผลลัพธ์เป็นรูปแบบ Base64 เพื่อให้ได้ลายเซ็นที่คาดหวัง

4. เปรียบเทียบค่าลายเซ็นที่ดึงออกมากับลายเซ็นที่คาดหวัง หากคุณสร้างลายเซ็นได้อย่างถูกต้อง ค่าจะต้องเหมือนกัน

5. OPTIONAL

   เพื่อป้องกันการโจมตีแบบ replay ซึ่งเป็นประเภทของการโจมตีทางไซเบอร์ที่ผู้โจมตีดักจับและส่งข้อมูลซ้ำเพื่อเข้าถึงโดยไม่ได้รับอนุญาตหรือดำเนินการที่เป็นอันตราย การเปรียบเทียบค่าลายเซ็นที่ดึงออกมากับเวลาปัจจุบันและตรวจสอบให้แน่ใจว่าตกอยู่ในขอบเขตเวลาที่เหมาะสมจะเป็นประโยชน์ ตัวอย่างเช่น ขอบเขตเวลา 10 นาทีมักจะเป็นขอบเขตเวลาที่เหมาะสม

สคีมาของ Payload

เมื่อเหตุการณ์เป้าหมายของ webhook ของคุณถูกกระตุ้น มันจะส่งคำขอไปยัง URL ของ webhook ของคุณ รวมถึงข้อมูลเกี่ยวกับเหตุการณ์ใน payload Payload ทั้งหมดของคำขอจะแบ่งปันสคีมาที่ประกอบด้วยฟิลด์คงที่และฟิลด์ที่เปลี่ยนแปลง ซึ่งช่วยให้มั่นใจว่าข้อมูลที่ส่งใน payload มีโครงสร้างและสอดคล้องกัน ทำให้แอปพลิเคชันที่รับสามารถประมวลผลและใช้ข้อมูลได้ง่ายขึ้น

ฟิลด์สคีมาของ payload คงที่ สามารถช่วยรักษาความสอดคล้องในคำขอ webhook ทั้งหมด โดยมีฟิลด์ต่อไปนี้ที่มีให้:

1. NotificationId (string): รหัสประจำตัวที่ไม่ซ้ำกันสำหรับการแจ้งเตือนแต่ละรายการที่ส่ง หากได้รับ NotificationId เดียวกันสองครั้ง จะถือว่าเป็นการซ้ำกัน
2. EventType (string): ระบุประเภทของเหตุการณ์ที่การแจ้งเตือนถูกกระตุ้น
3. EventTime (string): เวลาที่เกิดเหตุการณ์

ฟิลด์สคีมาของ payload ที่เปลี่ยนแปลง ให้ความยืดหยุ่นสำหรับ webhook ในการรองรับประเภทของเหตุการณ์ที่หลากหลาย ซึ่งรวมถึง:

1. EventPayload (object): ประกอบด้วยข้อมูลเฉพาะเกี่ยวกับ EventType ที่กระตุ้น webhook โครงสร้างของสคีมาของ EventPayload จะแตกต่างกันไปตามประเภทของเหตุการณ์

ตัวอย่างต่อไปนี้แสดงสคีมาของ payload สำหรับเหตุการณ์ คำขอสิทธิในการลบข้อมูล:

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

จัดการการแจ้งเตือน

หากคุณเก็บ ข้อมูลที่สามารถระบุตัวตนได้ (PII) ของผู้ใช้ เช่น User IDs ของพวกเขา คุณควรประเมินคำขอในแง่ของข้อผูกพันทางกฎหมายของคุณ ข้อมูลเพิ่มเติมสามารถพบได้ใน RTBF และผู้สร้าง. คุณสามารถสร้างบอทเพื่อจัดการการแจ้งเตือน webhook และช่วยทำให้การลบข้อมูลเป็นไปโดยอัตโนมัติ โดยมีเงื่อนไขว่าคุณกำลังเก็บ PII ในที่เก็บข้อมูล ดูที่ การทำให้คำขอสิทธิในการลบข้อมูลเป็นไปโดยอัตโนมัติ สำหรับตัวอย่างวิธีการสร้างบอทภายใน Discord ที่ใช้ Open Cloud API สำหรับที่เก็บข้อมูล เพื่อลบข้อมูล PII เป็นโซลูชันอัตโนมัติ ตัวอย่างนี้สามารถปรับให้เข้ากับการจัดการการแจ้งเตือนอื่น ๆ เช่น เหตุการณ์การสมัครสมาชิก

หากคุณใช้จุดสิ้นสุดที่กำหนดเองเป็นเซิร์ฟเวอร์ webhook ของคุณแทนที่จะเป็นเครื่องมือของบุคคลที่สาม คุณสามารถดึงข้อมูลที่ต้องลบออกจาก payload ของ webhook และสร้างโซลูชันอัตโนมัติของคุณเอง ตัวอย่างโค้ดต่อไปนี้เป็นตัวอย่างของเซิร์ฟเวอร์ที่มีการป้องกันการโจมตีแบบ replay โดยการตรวจสอบ timestamp และว่าคำขอมาจาก Roblox:

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

const secret = '<your_secret>' // สามารถตั้งค่าเป็นตัวแปรสภาพแวดล้อมได้

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

app.all('/*', function (req, res) {
   console.log('มีคำขอใหม่เข้ามา');

   // ดึงค่า timestamp และ signature จากส่วนหัว
   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);

   // ตรวจสอบให้แน่ใจว่าคำขอมาจากภายในหน้าต่าง 300 วินาทีเพื่อป้องกันการโจมตีแบบ replay
   const requestTimestampMs = timestamp * 1000;
   const windowTimeMs = 300 * 1000;
   const oldestTimestampAllowed = Date.now() - windowTimeMs;

   if (requestTimestampMs < oldestTimestampAllowed) {
      return res.status(403).send('คำขอหมดอายุ');
   }

   // ตรวจสอบลายเซ็น
   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('คำขอไม่ได้รับอนุญาต');
   }

   // โลจิกของคุณในการจัดการ 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: UserId=${userId} และ GameIds=${gameIds}`);
      // หากคุณเก็บ PII ในที่เก็บข้อมูล ให้ใช้ UserId และ GameIds เพื่อลบข้อมูลจากที่เก็บข้อมูล
   }

   return res.json({ message: 'ประมวลผลข้อความสำเร็จ' });
});

app.listen(8080, function () {
   console.log('เซิร์ฟเวอร์เริ่มต้นแล้ว');
});