Notifikasi webhook

Alih-alih memantau secara manual semua peristiwa dalam pengalaman Anda dan permintaan dari pengguna, Anda dapat mengatur webhook untuk menerima pemberitahuan waktu nyata pada alat pesan instan pihak ketiga atau endpoint khusus Anda yang dapat menerima permintaan HTTP.Ini membantu Anda mengotomatisasi alur kerja manajemen notifikasi Anda untuk mengurangi pengelolaan notifikasi upaya manual.

Saat ini, Roblox sepenuhnya mendukung pemberitahuan webhook untuk Discord, Guilded, dan Slack.Menggunakan webhook dengan alat pihak ketiga lainnya membawa risiko tidak menerima semua notifikasi.

Alur kerja Webhook

Webhook mengirim pemberitahuan atau data waktu nyata antara dua aplikasi atau layanan yang berbeda, seperti Roblox dan alat pesan pihak ketiga.Tidak seperti API tradisional, yang memerlukan Anda untuk mengatur aplikasi klien untuk mengirim permintaan ke server untuk menerima data, webhook mengirim data ke akhir klien Anda segera setelah terjadi peristiwa.Mereka berguna untuk otomatisasi alur kerja antara Roblox dan aplikasi pihak ketiga yang Anda gunakan untuk berkolaborasi dengan tim Anda, karena mereka memungkinkan berbagi dan pemrosesan data real time.

Setelah Anda mengatur webhook, setiap kali terjadi peristiwa target, Roblox mengirim permintaan ke URL webhook yang Anda berikan.URL webhook kemudian mengarahkan ulang permintaan ke aplikasi penerima atau titik akhir khusus, yang dapat mengambil tindakan berdasarkan data yang termasuk dalam pembayaran webhook.Ini bisa termasuk menghapus data untuk GDPR, mengirim konfirmasi kepada pengguna, atau memicu acara lain.

Pemicu yang didukung

Roblox saat ini mendukung pemicu acara berikut.

Langganan

Langganan Diresubscribe Kembali - Ketika pengguna mengubah langganan ke langganan, pesan dikirim yang berisi langganan dan pengguna.
Langganan Diperbarui - Ketika pengguna memperbarui langganan, pesan dikirim yang berisi langganan dan penerima.
Pengembalian Langganan - Ketika pengguna menerima pengembalian untuk langganan mereka, pesan dikirim yang berisi langganan dan pengguna.
Langganan Dibeli - Ketika pengguna membeli langganan, pesan dikirim yang berisi langganan dan penerima.
Langganan dibatalkan - Ketika pengguna membatalkan langganan , pesan dikirim yang berisi langganan dan penerima, serta alasan yang diberikan untuk pembatalan.

Untuk informasi lebih lanjut tentang acara berlangganan dan bidangnya, lihat referensi Langganan.

Kepatuhan

Hak untuk Permintaan Penghapusan Data - Ketika pengguna mengirim permintaan penghapusan data di bawah Peraturan Umum Perlindungan Data (GDPR).

Perdagangan

Pengembalian Pesanan Produk Perdagangan Dikembalikan - Ketika pengguna telah menerima pengembalian atas pesanan produk perdagangan mereka, atau pesanan dibatalkan.
Pesanan Produk Perdagangan Dibayar - Ketika pengguna telah membayar pesanan produk perdagangan mereka.Harap dicatat bahwa acara webhook duplikat adalah mungkin, jadi Anda harus menghapus acara menggunakan ID pesanan perdagangan unik.

Konfigurasi webhook di Dashboard Pencipta

Untuk menerima notifikasi melalui webhook, Anda perlu mengonfigurasi webhook yang berlangganan ke acara tertentu untuk memicu notifikasi.Untuk pengalaman milik kelompok, hanya pemilik kelompok yang dapat mengkonfigurasi dan menerima notifikasi webhook.

Jika Anda mengatur webhook dan menangani data pribadi, pastikan mereka mematuhi Peraturan Umum Perlindungan Data (GDPR).

Untuk mengatur webhook:

Navigasikan ke bagian Webhooks dari Dashboard Pencipta.
Klik tombol Tambahkan Webhook .
Selesaikan bidang konfigurasi:
1. URL Webhook - Tentukan URL di mana Anda ingin menerima pemberitahuan.Untuk informasi lebih lanjut tentang persyaratan, lihat Buat URL webhook.
2. Nama - Gunakan nama khusus untuk membedakan konfigurasi Anda dari yang lain. Nilai default adalah sama dengan URL Webhook.
3. Rahasia (opsional) - Berikan rahasia jika Anda ingin memverifikasi bahwa pemberitahuan yang Anda terima berasal dari Roblox.Untuk informasi lebih lanjut, lihat Verifikasi keamanan webhook.
4. Pemicu - Pilih satu atau lebih opsi dari daftar pemicu yang didukung dari peristiwa yang ingin Anda terima pemberitahuan.
Klik tombol Simpan Perubahan .

Saat ini, Anda dapat mengonfigurasi hingga 5 webhook secara total.

Menyiapkan URL webhook

Anda dapat mengatur titik akhir layanan HTTP khusus sebagai URL webhook Anda, asalkan memenuhi persyaratan berikut:

Ini harus diakses publik untuk menangani permintaan.
Ini dapat menangani permintaan POST.
Ini dapat menanggapi permintaan dengan respons 2XX dalam 5 detik.
Ini dapat menangani permintaan HTTPS.

Ketika akhir Anda menerima permintaan POST, itu harus dapat:

Ekstrak rincian yang diperlukan tentang pemberitahuan dari tubuh pesan POST.
Baca tubuh pesan POST dengan rincian umum tentang pemberitahuan dan rincian spesifik terkait dengan jenis acara pada pemberitahuan.

Untuk informasi lebih lanjut tentang skema permintaan POST untuk ditangani, lihat Skema Payload.

Kebijakan gagal pengiriman ulang

Ketika pemberitahuan webhook gagal mencapai URL yang ditentukan karena kesalahan seperti tidak tersediannya endpoint, Roblox mencoba kirim ulang pesan ke URL yang dikonfigurasi 5 kali menggunakan ukuran jendela tetap.Jika pemberitahuan masih gagal dikirim setelah 5 upaya, Roblox berhenti mencoba mengirim pemberitahuan dan asumsi bahwa URL tidak lagi valid.Dalam situasi ini, Anda perlu memperbarui konfigurasi webhook Anda dengan URL baru yang dapat diakses dan dapat menerima notifikasi.Untuk memecahkan masalah dan mengkonfirmasi bahwa URL webhook Anda dapat menerima pemberitahuan dengan sukses, lihat Tes webhook.

Persyaratan pihak ketiga

Alat pihak ketiga biasanya memiliki persyaratan sendiri untuk webhook yang perlu Anda ikuti saat mengatur URL webhook Anda.Anda dapat menemukan persyaratan ini dengan mencari kata kunci "webhook" di situs dukungan atau dokumentasi alat target.Untuk tiga alat pihak ketiga yang didukung, lihat berikut:

Menguji webhook

Anda dapat menguji apakah webhook yang Anda konfigurasi dapat berhasil menerima pemberitahuan di Dashboard Pencipta:

Navigasikan ke halaman konfigurasi Webhook.
Pilih webhook yang ingin Anda uji dari daftar webhook yang dikonfigurasi.
Klik ikon pensil di sebelah webhook target.
Klik tombol Balasan Tes .

Sistem kemudian mengirimkan acara SampleNotification , yang termasuk ID Pengguna **** dari pengguna yang memicu pemberitahuan, seperti yang ditunjukkan di sini:

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

Jika Anda mengintegrasikan webhook Anda dengan layanan pihak ketiga, Anda dapat menguji dengan menggunakan URL pihak ketiga untuk memastikan bahwa layanan dapat berhasil menerima pemberitahuan dari webhook Anda.Jika Anda memberikan rahasia saat mengkonfigurasi webhook, itu juga menghasilkan roblox-signature yang dapat Anda gunakan untuk menguji logika roblox-signature.

Verifikasi keamanan webhook

Setelah Anda mengkonfigurasi server untuk menerima pengiriman, ia mulai mendengarkan pengiriman apa pun yang dikirim ke endpoint.Jika Anda mengatur rahasia saat mengkonfigurasi webhook, Roblox mengirimkan roblox-signature di setiap pemberitahuan webhook untuk memastikan bahwa permintaan sebenarnya berasal dari Roblox.Tanda tangan ada di header payload untuk akhiran khusus dan di footer untuk server pihak ketiga.

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

Jika Anda tidak mengatur rahasia untuk webhook Anda, tanda tangan hanya berisi waktu戳 ketika notifikasi dikirim:

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

Untuk memverifikasi tanda tangan:

Ekstrak nilai timestamp dan tanda tangan.Semua tanda tangan untuk webhook dengan rahasia berbagi format yang sama dengan string CSV dengan dua nilai ini diikuti oleh pr prefiks:
- t : Stempel waktu ketika notifikasi dikirim.
- v1 : Nilai tanda tangan yang dihasilkan menggunakan rahasia yang disediakan oleh konfigurasi Dashboard Pencipta.
Buat ulang string dasar dari roblox-signature dengan menyambungkan:
1. timestamp sebagai string.
2. Karakter periode . .
3. String JSON dari tubuh permintaan.
Hitung kode otentikasi pesan berbasis hash (HMAC) dengan fungsi hash SHA256 menggunakan kunci rahasia yang Anda definisikan selama konfigurasi sebagai kunci dan string dasar yang dihasilkan melalui langkah 2 sebagai pesan.Konversi hasil ke format Base64 untuk mendapatkan tanda tangan yang diharapkan.
Bandingkan nilai tanda tangan yang diambil dengan tanda tangan yang diharapkan. Jika Anda menghasilkan tanda tangan dengan benar, nilainya harus sama.
(Opsi) Untuk mencegah serangan replay, jenis serangan siber di mana penyerang menangkap dan mengirim ulang data untuk mendapatkan akses tidak sah atau melakukan tindakan jahat, bermanfaat untuk membandingkan nilai waktu pencatatan yang diambil dengan waktu pencatatan saat ini dan memastikan jatuh dalam batas waktu yang wajar.Sebagai contoh, jendela 10 menit biasanya merupakan batas waktu yang bagus dan masuk akal.

Skema beban

Ketika peristiwa target webhook Anda diaktifkan, ia mengirim permintaan ke URL webhook Anda, termasuk informasi tentang peristiwa dalam payload.Semua pengiriman permintaan berbagi skema yang sama yang terdiri dari bidang tetap dan variabel.Ini memastikan bahwa data yang dikirim dalam payload terstruktur dan konsisten, sehingga lebih mudah bagi aplikasi penerima untuk memproses dan menggunakan data.

Bidang skema pemuatan tetap dapat membantu menjaga konsistensi di semua permintaan webhook, dengan bidang berikut yang tersedia:

NotificationId (string): Pengenal unik untuk setiap pemberitahuan yang dikirim. Jika yang sama NotificationId diterima dua kali, dianggap duplikat.
EventType (string): Menunjukkan jenis acara untuk mana pemberitahuan dapat diaktifkan.
EventTime (string): Stempel waktu ketika acara dipicu.

The variabel payload schema bidang memberikan fleksibilitas bagi webhook untuk menampung berbagai jenis acara, yang termasuk:

EventPayload (objek): Berisi informasi khusus untuk EventType yang memicu webhook.Struktur skema EventPayload bervariasi tergantung pada jenis acara.

Contoh berikut menunjukkan skema payload dari permintaan Hapus Kanan peristiwa:

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

Tangani notifikasi

Jika Anda menyimpan informasi Pengenal Pribadi (PII) dari pengguna Anda, seperti User ID mereka, Anda harus menghapus informasi ini saat pengguna mengirimkan permintaan seperti itu untuk mematuhi persyaratan kepatuhan GDPR hak untuk menghapus.Anda dapat membuat bot untuk menangani notifikasi webhook dan membantu otomatisasi penghapusan data, asalkan Anda menyimpan PII di penyimpanan data.Lihat Otomatisasi Hak untuk Menghapus Permintaan Penghapusan untuk contoh tentang cara membuat bot di Guilded atau Discord yang menggunakan Open Cloud API untuk penyimpanan data untuk menghapus data PII sebagai solusi otomatisasi.Contoh ini dapat disesuaikan untuk menangani notifikasi lain, seperti peristiwa berlangganan.

Jika Anda menggunakan endpoint khusus sebagai server webhook Anda alih-alih alat pihak ketiga, Anda dapat mengekstrak data yang akan dihapus dari payload webhook dan membangun solusi otomatisasi Anda sendiri.Contoh kode berikut adalah contoh server yang memiliki pencegahan terhadap serangan replay dengan memverifikasi timestamp dan bahwa permintaan berasal dari 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');
});

Di halaman ini