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

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

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

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

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

การดักที่สนับสนุน

ขณะนี้ Roblox สนับสนุนการเรียกการเหตุการณ์ต่อไปนี้

สมัครสมาชิก

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

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

การสอดคล้อง

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

การค้า

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

กำหนดค่าเว็บฮุคบนแดชบอร์ดของผู้สร้าง

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

เพื่อตั้งค่าเว็บฮุค:

1. ไปที่ส่วน เว็บฮุค ของแดชบอร์ดผู้สร้าง
2. คลิกที่ปุ่ม เพิ่ม Webhook 3. เสร็จสิ้นฟิลด์การกำหนดค่า:

   1. URL ของเว็บฮุค - ระบุ URL ที่คุณต้องการรับการแจ้งเตือนสำหรับข้อมูลเพิ่มเติมเกี่ยวกับข้อกําหนดให้ดูที่ ตั้งค่า URL สําหรับเว็บฮุค
   2. ชื่อ - ใช้ชื่อที่กําหนดเองเพื่อแยกแยะการกำหนดค่าของคุณจากคนอื่น โดยค่าเริ่มต้นจะเป็นเช่นเดียวกับ URL Webhook
   3. ลับ (ตัวเลือก) - จัดหาลับถ้าคุณต้องการตรวจสอบว่าการแจ้งเตือนที่คุณได้รับมาจาก Robloxสำหรับข้อมูลเพิ่มเติม ดู ตรวจสอบความปลอดภัยของเว็บฮุค
   4. ตัวกระตุ้น - เลือกหนึ่งหรือมากกว่าตัวเลือกจากรายการ ตัวกระตุ้นที่สนับสนุน ของเหตุการณ์ที่คุณต้องการรับการแจ้งเตือน
3. คลิกที่ปุ่ม บันทึกการเปลี่ยนแปลง

ตั้งค่า URL ของเวบฮุค

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

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

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

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

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

นโยบายการล้มเหลวในการส่งมอบใหม่

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

ความต้องการของบุคคลที่สาม

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

• ศูนย์ช่วยเหลือของ Discord
• การสนับสนุน Guilded
• คู่มือ API Slack

ทดสอบ webhooks

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

1. นําทางไปยังหน้าการกำหนดค่า Webhooks
2. เลือกเว็บฮุคที่คุณต้องการทดสอบจากรายการเว็บฮุคที่กำหนดค่าไว้
3. คลิกไอคอนดินสอต่อกับเว็บฮุคเป้าหมาย
4. คลิกที่ปุ่ม การตอบสนองการทดสอบ ระบบจะส่งอีเวนต์ SampleNotification ซึ่งรวมถึง ID ผู้ใช้ ของผู้ใช้ที่กระตุ้นการแจ้งเตือน เช่นเดียวกับที่แสดงไว้ที่นี่:

สคริปต์ภาพรวมการแจ้งเตือนตัวอย่าง
{
  "NotificationId": "string",
  "EventType": "SampleNotification",
  "EventTime": "2023-12-30T16:24:24.2118874Z",
  "EventPayload": {
    "UserId": 1
  }
}

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

ตรวจสอบความปลอดภัยของเว็บฮุค

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

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

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

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

เพื่อตรวจสอบลายเซ็น:

1. สกัดค่าเวลาและลายเซ็นลายเซ็นทั้งหมดสำหรับ webhooks ที่มีความลับแบ่งปันรูปแบบเดียวกับข้อความ CSV ที่มีค่าสองตัวต่อไปนี้ตามด้วยคํานําหน้า:

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

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

   1. เวลาที่เป็นข้อความเป็น timestamp
   2. ตัวละครระยะเวลา . .
   3. สตริง JSON ของร่างคำขอ

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

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

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

สคริปต์โหลดข้อมูล

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

ฟิลด์สเครื่องหมายจ่ายคงที่ ที่แก้ไขได้ สามารถช่วยในการรักษาความสอดคล้องข้ามคำขอเว็บฮุคทั้งหมดด้วยฟิลด์ที่มีอยู่ดังต่อไปนี้:

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

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

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

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

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

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

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

หากคุณใช้จุดสิ้นสุดที่กําหนดเองเป็นเซิร์ฟเวอร์เว็บฮุคแทนเครื่องมือบุคคลที่สาม คุณสามารถสกัดข้อมูลที่ต้องลบออกจากเว็บฮุกเพย์โหลดและสร้างโซลูชันอัตโนมัติของคุณเองตัวอย่างโค้ดต่อไปนี้เป็นตัวอย่างของเซิร์ฟเวอร์ที่มีการป้องกันการโจมตีรีเพลย์โดยการตรวจสอบเวลาที่เกิดเหตุและที่คำขอมาจาก 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');
});