Daripada secara manual memantau semua acara di pengalaman Anda dan permintaan dari pengguna, Anda dapat mengatur webhook untuk menerima notifikasi real time di alat pesan lain atau ujung pengguna Anda yang dapat menerima permintaan HTTP. Ini membantu Anda untuk mengotomatisasi alur kerja notifikasi Anda untuk mengurangi upaya pengiriman manual.
Saat ini, Roblox sepenuhnya mendukung notifikasi webhook untuk Discord, Guilded, dan Slack. Menggunakan webhook dengan alat pihak ketiga berisiko tidak menerima semua notifikasi.
Kerja Mengguna Webhook
Webhook mengirim notifikasi atau data antara dua aplikasi atau layanan yang berbeda, seperti Roblox dan alat pesanan pihak ketiga. Tidak seperti API tradisional yang mengharuskan Anda untuk menginstal aplikasi klien untuk mengirim permintaan ke server untuk menerima data, webhook mengirim data ke client Anda segera setelah acara
Setelah Anda menyiapkan webhook, setiap kali acara target terjadi, Roblox mengirim permintaan ke URL webhook yang Anda menyediakan. URL webhook kemudian mengalihkan permintaan ke aplikasi penerimaan Anda atau titik akhir khusus, yang dapat mengambil tindakan berdasarkan data yang disertakan dalam webhook. Ini dapat mencakup menghapus data untuk GDPR, mengirim konfirmasi ke pengguna, atau
Pendukung Trigger
Roblox saat ini mendukung berbagai pengganda acara untuk notifikasi:
- Langganan Dibatalkan - Ketika seorang pengguna menyetor langganan, pesan dikirim mengandung langganan dan subscriber, serta alasan yang diberikan untuk pembatalan.
- Langganan Dibeli - Saat seorang pengguna membeli langganan, pesan dikirim mengandung langganan dan subscriber.
- Langganan Dikembalikan - Saat seorang pengguna menerima pengembalian dana langganan mereka, pesan dikirim mengandung langganan dan subscriber.
- Langganan Diperbarui - Saat seorang pengguna menyetujui langganan, pesan dikirim mengandung langganan dan subscriber.
- Langganan Diberlangganan Kembali - Saat seorang pengguna mengikuti kembali langganan, pesan dikirim mengandung langganan dan subscriber.
- "Hak untuk dilupakan" permintaan penghapusan data di bawah Peraturan Umum Data Korupsi ( GDPR ).
Untuk lebih banyak informasi tentang acara berlangganan dan lapangannya, lihat referensi Cloud API Subscription.
Mengkonfigurasi Webhook di Dasbor Kreator
Untuk menerima notifikasi melalui webhook, Anda harus mengkonfigurasi webhook yang berlangganan ke beberapa acara untuk menyetel notifikasi. Untuk pengalaman dimiliki grup, hanya pemilik grup yang dapat mengkonfigurasi dan menerima notifikasi webhook.
Jika Anda mengatur webhook dan menangani data pribadi, pastikan mereka mematuhi aturan Peraturan Umum Pengelolaan Data (GDPR).
Untuk menyiapkan webhook:
- Navigate to the Webhook section of the Dashboard Pembuat .
- Klik tombol Tambahkan Webhook .
- Selesaikan lapangan konfigurasi:
- URL Webhook — Spesifikasi URL di mana Anda ingin menerima notifikasi dan menerima URL webhook yang masuk dari entitas pihak ketiga. Untuk informasi lebih lanjut tentang persyaratan, lihat Mengatur URL Webhook.
- Nama — Gunakan nama khusus untuk mendistinkan konfigurasi Anda dari orang lain. Secara default, nilai adalah sama dengan URL Webhook Anda.
- Rahasia (opsional) — Berikan rahasia jika Anda ingin memverifikasi bahwa notifikasi yang Anda terima berasal dari Roblox. Untuk lebih banyak informasi, lihat Verifying Webhook Security.
- Pengaktifan — Pilih satu atau lebih opsi dari daftar pengaktifan dukungan acara untuk menerima notifikasi.
- Klik tombol Simpan Perubahan .
Saat ini, Anda dapat mengkonfigurasi hingga 5 webhook total.
Mengatur URL Webhook
Anda dapat mengatur HTTP service endpoint khusus sebagai URL webhook Anda, asalkan itu memenuhi persyaratan berikut:
- Harus dapat diakses publik untuk menangani permintaan.
- Dapat menangani permintaan POST.
- Dapat menjawab permintaan dengan respons 2XX dalam waktu 5 detik.
- Dapat menangani permintaan HTTPS.
Ketika端口 Anda menerima permintaan POST, itu harus dapat:
- Ekstraksi rincian yang dibutuhkan tentang notifikasi dari tubuh pesan POST.
- Baca tubuh pesan POST dengan rincian umum tentang pengumuman dan rincian spesifik terkait jenis acara pada notifikasi.
Untuk lebih banyak informasi tentang schema permintaan POST untuk ditangani, lihat Payload Schema.
Kebijakan Pengiriman Ulang
Ketika notifikasi webhook gagal mencapai URL yang ditentukan karena kesalahan seperti ketidakavailabilityan端口, Roblox mencoba kembali mengirim pesan ke URL yang ditentukan 5 kali menggunakan ukuran jendela tetap. Jika notifikasi masih gagal ditangani setel
Persyaratan Pihak Ketiga
Alat pihak ketiga biasanya memiliki persyaratan mereka sendiri untuk webhook yang Anda perlukan untuk menyiarkan URL webhook Anda. Anda dapat menemukan persyaratan ini dengan mencari kata kunci "webhook" di situs dukungan atau dokumenasi tool target. Untuk tiga alat pihak ketiga yang didukung, lihat mengikuti:
Menguji Webhook
Anda dapat menguji apakah webhook yang Anda konfigurasikan dapat menerima notifikasi dengan sukses di Creator Dashboard :
Navigate to the Webhook konfigurasi halaman.
Pilih webhook yang ingin Anda tes dari daftar webhook yang dikonfigurasikan.
Klik ikon pensil di samping target webhook.
Klik tombol Tanggapan Pengujian .
Sistem kemudian mengirim notifikasi dalam jenis SampleNotification, yang termasuk User ID dari pengguna yang memicu notifikasi, seperti yang ditunjukkan oleh contoh skema berikut:
Skema Pemberitahuan Sampel
Body: {
"NotificationId": "string",
"EventType": "SampleNotification",
"EventTime": "2023-12-30T16:24:24.2118874Z", // Jenis: Tim戳 ISO 8601
"EventPayload": {
"UserId": 1 // Jenis: Panjang
}
}
Jika Anda mengintegrasi webhook Anda dengan layanan pihak ketiga, Anda dapat menguji menggunakan URL pihak ketiga untuk mengonfirmasi bahwa layanan dapat dengan sukses menerima notifikasi dari webhook Anda. Jika Anda menyediakan rahasia saat mengkonfigurasi webhook, itu juga menghasilkan roblox-signature yang dapat Anda gun
Verifikasi Keamanan Webhook
Setelah Anda mengkonfigurasi server Anda untuk menerima pemuatan, itu mulai mendengarkan untuk setiap pemuatan yang dikirim ke endpoint. Jika Anda menetapkan rahasia saat mengkonfigurasi webhook Anda, Roblox mengirimkan roblox-signature bersama dengan setiap pengiriman not
Signature Format with Secret for Custom Endpoints
Jika Anda tidak memiliki rahasia untuk webhook Anda, tanda tangani yang Anda terima hanya berisi nilai waktu pada saat notifikasi dikirim:
Signature Format without Secret for Custom Endpoints
Untuk mengevaluasi tanda tangani:
Ekstraksi nilai tanggal dan tanda tangani. Semua tanda tangani untuk webhook dengan rahasia berbagi format yang sama seperti CSV string dengan dua nilai ini setelah huruf- huruf pengikut:
- t :Nilai waktu pengiriman notifikasi.
- v1 :Nilai tanda tangani yang dihasilkan menggunakan konfigurasi Creator Dashboard yang disediakan. Anda dapat mengekstraksi kedua nilai ini menggunakan fungsi split(), yang memisahkan string berdasarkan delimiter, dalam hal ini, karakter ,.
Buat ulang string dasar roblox-signature dengan menyatukan:
- Waktu pada saat ini sebagai string.
- Karakter periode . .
- String JSON permintaan tubuh.
Komputasi kode verifikasi pesan berbasis hash (HMAC) dengan fungsi hash secret yang Anda definisikan selama konfigurasi sebagai kunci dan string base yang Anda generasi melalui langkah 2 sebagai pesan. Konversi hasil ke format Base64 untuk mendapatkan tanda tangani yang diharapkan.
Bandingkan nilai tanda yang diambil dengan tanda yang diharapkan. Jika Anda menghasilkan tanda dengan benar, nilai harus sama.
(Opsional) Untuk mencegah serangan ulang, jenis serangan siber di mana penyerang menginterupsi dan mengirim kembali data untuk mendapatkan akses tidak autorisasi atau melakukan tindakan jahat, itu membantu untuk membandingkan nilai timestamp yang diambil dengan saat ini dan memastikan bahwa itu jatuh dalam batas waktu yang masuk akal. Misalnya, jendela 10 menit biasanya merupakan batas waktu yang
Skema Pembayaran
Ketika acara target dari webhook Anda dipicu, itu mengirim permintaan ke URL webhook Anda, termasuk informasi tentang acara di payload. Semua webhook request berbagi schema yang terdiri dari field yang tetap dan variabel. Ini menjamin bahwa data yang dikirim dalam payload distruktur dan konsisten, sehingga lebih mudah bagi aplikasi yang menerima untuk memproses dan menggunakan data.
field pemuatan penggunaan tetap yang dapat diperbaiki dapat membantu menjaga konsistensi di semua permintaan webhook, dengan field pemuatan penggunaan tersedia berikut:
- NotificationId , string : Pengenal unik untuk setiap pengumuman dikirim. Jika yang sama NotificationId diterima dua kali, itu dianggap duplikat.
- EventType , string : Sebuah string mewakili jenis acara untuk setiap pengumuman yang diaktifkan.
- EventTime , timestamp : Waktu戳 kira-kira menunjukkan kapan acara diaktifkan.
variabel skema pemuatan memberikan fleksibilitas bagi webhook untuk menampung berbagai jenis acara, termasuk:
- EventPayload , object : Berisi informasi spesifik untuk EventType yang mengaktifkan webhook. Struktur 0> EventPayload0> schema bervariasi tergantung jenis acara.
Contoh berikut menunjukkan schema pemuatan penggunaan Permintaan Hak Hapus acara:
Contoh Schema untuk Permintaan Hak Hapus
Body:{
"NotificationId": "string",
"EventType": "RightToErasureRequest",
"EventTime": "2023-12-30T16:24:24.2118874Z",
"EventPayload": {
"UserId": 1, // Jenis: Panjang
"GameIds": [ // Jenis: Sebuah array dari Longs
1234, 2345
]
}
}
Penanganan Notifikasi
Jika Anda menyimpan informasi yang Dapat Dipengaruhi Secara Pribadi (PII) dari pengguna Anda, seperti ID Peng
Jika Anda menggunakan endpoint khusus sebagai server webhook Anda alih-alih alat pihak ketiga, Anda dapat mengekstraksi data subjek untuk dihapus dari webhook payload dan membangun solusi otomatisasi Anda sendiri. Contoh kode berikut memberikan solusi contoh dan menambahkan solusi pencegahan untuk menghapus serangan ulang dengan memverifikasi bahwa permintaan berasal dari 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')
})