Notifikasi webhook

Alih-alih memantau semua peristiwa dalam permainan Anda dan permintaan dari pengguna secara manual, Anda dapat mengatur webhook untuk menerima notifikasi waktu nyata di alat pesan pihak ketiga atau titik akhir kustom Anda yang dapat menerima permintaan HTTP. Ini membantu Anda mengotomatiskan alur kerja manajemen notifikasi Anda untuk mengurangi upaya manual dalam menangani notifikasi.

Alur kerja webhook

Webhook mengirimkan notifikasi atau data waktu nyata antara dua aplikasi atau layanan yang berbeda, seperti Roblox dan alat pesan pihak ketiga. Berbeda dengan API tradisional, yang mengharuskan Anda untuk mengatur aplikasi klien untuk mengirim permintaan ke server untuk menerima data, webhook mengirimkan data ke titik akhir klien Anda segera setelah peristiwa terjadi. Mereka berguna untuk mengotomatiskan alur kerja antara Roblox dan aplikasi pihak ketiga yang Anda gunakan untuk berkolaborasi dengan tim Anda, karena mereka memungkinkan berbagi dan pemrosesan data secara waktu nyata.

Setelah Anda mengatur webhook, setiap kali peristiwa target terjadi, Roblox mengirimkan permintaan ke URL webhook yang Anda berikan. URL webhook kemudian mengalihkan permintaan ke aplikasi penerima Anda atau titik akhir kustom, yang dapat mengambil tindakan berdasarkan data yang termasuk dalam payload webhook. Ini bisa termasuk menghapus data untuk kepatuhan RTBF, mengirim konfirmasi kepada pengguna, atau memicu peristiwa lain.

Pemicu yang didukung

Roblox saat ini mendukung pemicu peristiwa berikut.

Langganan

• Langganan Didaftarkan Kembali - Ketika seorang pengguna mendaftar kembali ke langganan, sebuah pesan dikirim yang berisi langganan dan pelanggan.
• Langganan Diperpanjang - Ketika seorang pengguna memperpanjang langganan, sebuah pesan dikirim yang berisi langganan dan pelanggan.
• Langganan Dikembalikan - Ketika seorang pengguna menerima pengembalian dana untuk langganan mereka, sebuah pesan dikirim yang berisi langganan dan pelanggan.
• Langganan Dibeli - Ketika seorang pengguna membeli langganan, sebuah pesan dikirim yang berisi langganan dan pelanggan.
• Langganan Dibatalkan - Ketika seorang pengguna membatalkan langganan, sebuah pesan dikirim yang berisi langganan dan pelanggan, serta alasan yang diberikan untuk pembatalan.

Untuk informasi lebih lanjut tentang peristiwa langganan dan bidangnya, lihat referensi Langganan.

Kepatuhan

• Hak untuk Dihapus / Permintaan Penghapusan - Ketika seorang pengguna menggunakan hak mereka untuk menghapus informasi pribadi mereka secara permanen sesuai dengan peraturan perlindungan data dan privasi global yang berlaku. Informasi lebih lanjut dapat ditemukan di RTBF dan Kreator.

Perdagangan

• Pesanan Produk Perdagangan Dikembalikan - Ketika seorang pengguna telah menerima pengembalian dana untuk pesanan produk perdagangan mereka, atau pesanan tersebut dibatalkan.
• Pesanan Produk Perdagangan Dibayar - Ketika seorang pengguna telah membayar untuk pesanan produk perdagangan mereka. Harap dicatat bahwa peristiwa webhook duplikat mungkin terjadi, jadi Anda harus menduplikasi peristiwa menggunakan ID pesanan perdagangan yang unik.

Konfigurasi webhook di Dasbor Kreator

Untuk menerima notifikasi melalui webhook, Anda perlu mengonfigurasi webhook yang berlangganan ke peristiwa tertentu untuk memicu notifikasi. Untuk permainan yang dimiliki grup, hanya pemilik grup yang dapat mengonfigurasi dan menerima notifikasi webhook.

Untuk mengatur webhook:

1. Pilih pengalaman Anda di Creator Hub.

2. Di bawah Konfigurasi, pilih Webhook dan klik Tambahkan Webhook.

   URL webhook berasal dari penyedia Anda. Misalnya, URL Slack mungkin terlihat seperti ini:

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

3. Masukkan URL webhook Anda dan sebuah nama.

4. OPTIONAL

   Sertakan sebuah rahasia, yang membantu memastikan bahwa notifikasi yang Anda terima berasal dari Roblox. Untuk informasi lebih lanjut, lihat Verifikasi keamanan webhook.

5. Pilih satu atau lebih opsi dari daftar pemicu yang didukung peristiwa yang ingin Anda terima notifikasinya.

6. OPTIONAL

   Gunakan tombol Uji Respons untuk memeriksa apakah layanan Anda dapat menerima permintaan contoh.

7. Klik Simpan Perubahan.

Atur URL webhook

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

• Harus dapat diakses secara publik untuk menangani permintaan.
• Dapat menangani permintaan POST.
• Dapat merespons permintaan dengan respons 2XX dalam waktu 5 detik.
• Dapat menangani permintaan HTTPS.

Ketika titik akhir Anda menerima permintaan POST, ia harus dapat:

• Mengekstrak detail yang diperlukan tentang notifikasi dari badan pesan POST.
• Membaca badan pesan POST dengan detail umum tentang notifikasi dan detail spesifik terkait jenis peristiwa pada notifikasi.

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

Kebijakan pengulangan kegagalan pengiriman

Ketika notifikasi webhook gagal mencapai URL yang Anda tentukan karena kesalahan seperti ketidaktersediaan titik akhir, Roblox mencoba mengirimkan pesan ke URL yang dikonfigurasi 5 kali menggunakan ukuran jendela tetap. Jika notifikasi masih gagal dikirim setelah 5 percobaan, Roblox berhenti mencoba mengirim notifikasi dan menganggap bahwa URL tersebut tidak lagi valid. Dalam situasi ini, Anda perlu memperbarui konfigurasi webhook Anda dengan URL baru yang dapat dijangkau dan mampu menerima notifikasi. Untuk memecahkan masalah dan mengonfirmasi bahwa URL webhook Anda dapat berhasil menerima notifikasi, lihat Uji webhook.

Persyaratan pihak ketiga

Alat pihak ketiga biasanya memiliki persyaratan mereka 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 alat pihak ketiga yang didukung, lihat yang berikut ini:

• Pusat Bantuan Discord
• Referensi API Slack

Uji webhook

Anda dapat menguji apakah webhook yang telah Anda konfigurasikan dapat berhasil menerima notifikasi di Dasbor Kreator:

1. Navigasikan ke halaman konfigurasi Webhook.
2. Pilih webhook yang ingin Anda uji dari daftar webhook yang telah dikonfigurasi.
3. Klik ikon pensil di sebelah webhook target.
4. Klik tombol Uji Respons.

Sistem kemudian mengirimkan peristiwa SampleNotification, yang mencakup User ID dari pengguna yang memicu notifikasi, seperti yang ditunjukkan di sini:

{
  "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 mengujinya menggunakan URL pihak ketiga untuk mengonfirmasi bahwa layanan tersebut dapat berhasil menerima notifikasi dari webhook Anda. Jika Anda memberikan rahasia saat mengonfigurasi webhook, itu juga menghasilkan roblox-signature yang dapat Anda gunakan untuk menguji logika roblox-signature.

Verifikasi keamanan webhook

Setelah Anda mengonfigurasi server Anda untuk menerima payload, ia mulai mendengarkan setiap payload yang dikirim ke titik akhir. Jika Anda mengatur rahasia saat mengonfigurasi webhook Anda, Roblox mengirimkan roblox-signature dalam setiap notifikasi webhook untuk memastikan bahwa permintaan tersebut benar-benar berasal dari Roblox. Tanda tangan berada di header payload untuk titik akhir kustom dan di footer untuk server pihak ketiga.

t=<timestamp>,v1=<signature>

Jika Anda tidak mengatur rahasia untuk webhook Anda, tanda tangan hanya berisi timestamp saat notifikasi dikirim:

t=<timestamp>

Untuk memverifikasi tanda tangan:

1. Ekstrak nilai timestamp dan signature. Semua tanda tangan untuk webhook dengan rahasia memiliki format yang sama sebagai string CSV dengan dua nilai ini diikuti oleh prefiks:

   • t: Timestamp saat notifikasi dikirim.
   • v1: Nilai tanda tangan yang dihasilkan menggunakan rahasia yang diberikan oleh konfigurasi Dasbor Kreator.

2. Buat ulang string dasar dari roblox-signature dengan menggabungkan:

   1. Timestamp sebagai string.
   2. Karakter titik ..
   3. String JSON dari badan permintaan.

3. Hitung kode otentikasi pesan berbasis hash (HMAC) dengan fungsi hash SHA256 menggunakan rahasia yang Anda tentukan selama konfigurasi sebagai kunci dan string dasar yang Anda hasilkan melalui langkah 2 sebagai pesan. Ubah hasilnya ke format Base64 untuk mendapatkan tanda tangan yang diharapkan.

4. Bandingkan nilai tanda tangan yang diekstrak dengan tanda tangan yang diharapkan. Jika Anda menghasilkan tanda tangan dengan benar, nilainya harus sama.

5. OPTIONAL

   Untuk mencegah serangan pengulangan, jenis serangan siber di mana penyerang mencegat dan mengirim ulang data untuk mendapatkan akses tidak sah atau melakukan tindakan jahat, sangat membantu untuk membandingkan nilai timestamp yang diekstrak dengan timestamp saat ini dan memastikan bahwa itu berada dalam batas waktu yang wajar. Misalnya, jendela 10 menit biasanya merupakan batas waktu yang wajar.

Skema payload

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

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

1. NotificationId (string): Pengidentifikasi unik untuk setiap notifikasi yang dikirim. Jika NotificationId yang sama diterima dua kali, itu dianggap sebagai duplikat.
2. EventType (string): Menunjukkan jenis peristiwa untuk mana notifikasi dipicu.
3. EventTime (string): Timestamp saat peristiwa dipicu.

Bidang skema payload variabel memberikan fleksibilitas bagi webhook untuk mengakomodasi berbagai jenis peristiwa, yang mencakup:

1. EventPayload (object): Berisi informasi spesifik untuk EventType yang memicu webhook. Struktur skema EventPayload bervariasi berdasarkan jenis peristiwa.

Contoh berikut menunjukkan skema payload dari peristiwa Permintaan Hak untuk Dihapus:

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

Tangani notifikasi

Jika Anda menyimpan Informasi Pribadi yang Dapat Diidentifikasi (PII) dari pengguna Anda, seperti ID Pengguna mereka, Anda harus mengevaluasi permintaan tersebut sehubungan dengan kewajiban hukum Anda. Informasi lebih lanjut dapat ditemukan di RTBF dan Kreator. Anda dapat membuat bot untuk menangani notifikasi webhook dan membantu mengotomatiskan penghapusan data, asalkan Anda menyimpan PII dalam penyimpanan data. Lihat Mengotomatiskan Penghapusan Permintaan Hak untuk Dihapus untuk contoh tentang cara membuat bot di 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 langganan.

Jika Anda menggunakan titik akhir kustom sebagai server webhook Anda alih-alih alat pihak ketiga, Anda dapat mengekstrak data yang harus dihapus dari payload webhook dan membangun solusi otomatisasi Anda sendiri. Contoh kode berikut adalah contoh server yang memiliki pencegahan terhadap serangan pengulangan dengan memverifikasi timestamp dan bahwa permintaan berasal dari Roblox:

const crypto = require('crypto');
const express = require('express');

const secret = '<your_secret>' // Ini dapat diatur sebagai variabel lingkungan

let app = express();
app.use(express.json());

app.all('/*', function (req, res) {
   console.log('Permintaan baru diterima');

   // Ekstrak timestamp dan signature dari 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);

   // Pastikan permintaan datang dalam jendela 300 detik untuk mencegah serangan pengulangan
   const requestTimestampMs = timestamp * 1000;
   const windowTimeMs = 300 * 1000;
   const oldestTimestampAllowed = Date.now() - windowTimeMs;

   if (requestTimestampMs < oldestTimestampAllowed) {
      return res.status(403).send('Permintaan Kedaluwarsa');
   }

   // Validasi tanda tangan
   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('Permintaan Tidak Sah');
   }

   // Logika Anda untuk menangani payload
   const payloadBody = req.body;
   const eventType = payloadBody['EventType'];

   if (eventType === 'RightToErasureRequest'){
      const userId = payloadBody['EventPayload']['UserId'];
      const gameIds = payloadBody['EventPayload']['GameIds'];

      console.log(`Data payload: UserId=${userId} dan GameIds=${gameIds}`);
      // Jika Anda menyimpan PII dalam penyimpanan data, gunakan UserId dan GameIds untuk menghapus informasi dari penyimpanan data.
   }

   return res.json({ message: 'Pesan berhasil diproses' });
});

app.listen(8080, function () {
   console.log('Server dimulai');
});