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

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

ขั้นตอนการทำงานของ Webhook

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

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

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

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

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

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

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

ความสอดคล้อง

• คำขอสิทธิในการลบ - เมื่อผู้ใช้ส่งคำขอลบข้อมูลภายใต้ กฎระเบียบการคุ้มครองข้อมูลทั่วไป (GDPR)

คอมเมิร์ซ

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

นโยบายการ retry ในกรณีส่งไม่สำเร็จ

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

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

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

• Discord Help Center
• Slack API Reference

ทดสอบ webhook

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

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

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

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

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

ยืนยันความปลอดภัยของ webhook

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

รูปแบบลายเซนต์พร้อมความลับสำหรับจุดสิ้นสุดที่กำหนดเอง
t=<timestamp>,v1=<signature>

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

รูปแบบลายเซนต์ไม่มีความลับสำหรับจุดสิ้นสุดที่กำหนดเอง
t=<timestamp>

เพื่อยืนยันลายเซนต์:

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

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

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

   1. timestamp ในรูปแบบของสตริง
   2. ตัวอักษรจุด ..
   3. สตริง JSON ของร่างคำขอ

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

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

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

Schema ของ Payload

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

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

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

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

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

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

ตัวอย่าง schema สำหรับคำขอสิทธิในการลบ
{
   "NotificationId": "string",
   "EventType": "RightToErasureRequest",
   "EventTime": "2023-12-30T16:24:24.2118874Z",
   "EventPayload": {
      "UserId": 1,
      "GameIds": [
         1234, 2345
      ]
   }
}

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

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

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

การสกัด PII จาก Payload
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('เซิร์ฟเวอร์เริ่มทำงาน');
});