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

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

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

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

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

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

ขณะนี้ Roblox สนับสนุนการเรียกการเหตุการณ์ต่อไปนี้สำหรับการแจ้งเตือน:

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

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

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

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

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

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

   1. URL ของเว็บฮุค — ระบุ 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 ผู้ใช้ ของผู้ใช้ที่กระตุ้นการแจ้งเตือน ตามตัวอย่างสเคมาที่แสดงต่อไปนี้:

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

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

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

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

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

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

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

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

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

   • t : มูลค่าเวลาที่ส่งการแจ้งเตือนเมื่อส่ง
   • v1 : ค่าลายเซ็นที่สร้างขึ้นโดยใช้ค่าลับที่ให้โดยการกำหนดค่าแดชบอร์ดของผู้สร้างคุณสามารถสกัดค่าทั้งสองนี้โดยใช้ฟังก์ชัน split() ซึ่งแยกสตริงตามเครื่องแยกไว้ในกรณีนี้คือตัวอักษร ,

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

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

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

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

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

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

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

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

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

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

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

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

ตัวอย่างสเคมาสำหรับคำขอลบขวา
Body:{

   "NotificationId": "string",

   "EventType": "RightToErasureRequest",

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

   "EventPayload": {

      "UserId": 1, // ประเภท: ยาว

      "GameIds": [ // ประเภท: ชุดของ Longs

         1234, 2345

      ]

   }

}

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

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

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

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')
})