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 endpoint kustom Anda yang dapat menerima permintaan HTTP. Ini membantu Anda mengotomatiskan alur kerja manajemen notifikasi 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 mengatur aplikasi klien untuk mengirim permintaan ke server untuk menerima data, webhook mengirim data ke endpoint klien Anda segera setelah sebuah 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 tujuan terjadi, Roblox mengirimkan permintaan ke URL webhook yang Anda berikan. URL webhook kemudian mengarahkan permintaan ke aplikasi penerima Anda atau endpoint 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 - Saat seorang pengguna mendaftar kembali ke langganan, pesan dikirim yang berisi langganan dan pelanggan.
• Langganan Diperpanjang - Saat seorang pengguna memperpanjang langganan, pesan dikirim yang berisi langganan dan pelanggan.
• Langganan Dikembalikan - Saat seorang pengguna menerima pengembalian dana untuk langganannya, pesan dikirim yang berisi langganan dan pelanggan.
• Langganan Dibeli - Saat seorang pengguna membeli langganan, pesan dikirim yang berisi langganan dan pelanggan.
• Langganan Dibatalkan - Saat seorang pengguna membatalkan langganan, pesan dikirim yang berisi langganan dan pelanggan, serta alasan yang diberikan untuk pembatalan.

Untuk informasi lebih lanjut tentang peristiwa langganan dan field-nya, lihat referensi Langganan.

Kepatuhan

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

Perdagangan

• Pesanan Produk Perdagangan Dikembalikan - Saat seorang pengguna menerima pengembalian dana untuk pesanan produk perdagangannya, atau pesanan tersebut dibatalkan.
• Pesanan Produk Perdagangan Dibayar - Saat seorang pengguna telah membayar untuk pesanan produk perdagangannya. Harap dicatat bahwa peristiwa webhook yang 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 pada 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 Tambah Webhook.

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

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

3. Masukkan URL webhook dan nama.

4. (Opsional) Sertakan 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 peristiwa pemicu yang didukung yang ingin Anda terima notifikasinya.

6. (Opsional) Gunakan tombol Uji Respons untuk memeriksa apakah layanan Anda dapat menerima permintaan contoh.

7. Klik Simpan Perubahan.

Siapkan URL webhook

Anda dapat menetapkan endpoint layanan HTTP kustom sebagai URL webhook Anda, asalkan memenuhi persyaratan berikut:

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

Saat endpoint Anda menerima permintaan POST, ia harus dapat:

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

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

Kebijakan upaya pengiriman ulang

Saat notifikasi webhook gagal mencapai URL Anda yang ditentukan karena kesalahan seperti ketidaktersediaan endpoint, Roblox mencoba mengirim pesan ke URL yang dikonfigurasi sebanyak 5 kali menggunakan ukuran jendela tetap. Jika notifikasi masih gagal dikirim setelah 5 kali percobaan, Roblox berhenti mencoba mengirim notifikasi dan menganggap bahwa URL tersebut tidak valid lagi. Dalam situasi ini, Anda perlu memperbarui konfigurasi webhook Anda dengan URL baru yang dapat dijangkau dan dapat menerima notifikasi. Untuk menyelesaikan masalah dan mengonfirmasi bahwa URL webhook Anda dapat menerima notifikasi dengan sukses, 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 menerima notifikasi dengan sukses di Dasbor Kreator:

1. Arahkan ke halaman konfigurasi Webhook.
2. Pilih webhook yang ingin Anda uji dari daftar webhook terkonfigurasi.
3. Klik ikon pensil di samping webhook target.
4. Klik tombol Uji Respons.

Sistem kemudian mengirimkan peristiwa SampleNotification, yang menyertakan ID Pengguna 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 menerima notifikasi dari webhook Anda dengan sukses. 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 untuk payload apa pun yang dikirim ke endpoint. Jika Anda mengatur rahasia saat mengonfigurasi webhook, Roblox mengirimkan roblox-signature dalam setiap notifikasi webhook untuk memastikan bahwa permintaan tersebut benar-benar berasal dari Roblox. Tanda tangan ada di header payload untuk endpoint kustom dan di footer untuk server pihak ketiga.

t=<timestamp>,v1=<signature>

Jika Anda tidak mengatur rahasia untuk webhook Anda, tanda tangan hanya berisi cap waktu kapan 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 seperti string CSV dengan dua nilai ini diikuti oleh prefiks:

   • t: Cap waktu 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. Cap waktu sebagai string.
   2. Karakter titik ..
   3. String JSON dari badan permintaan.

3. Hitung kode autentikasi pesan berbasis hash (HMAC) dengan fungsi hash SHA256 menggunakan rahasia yang Anda definisikan selama konfigurasi sebagai kunci dan string dasar yang Anda buat melalui langkah 2 sebagai pesan. Ubah hasilnya menjadi 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. (Opsional) Untuk mencegah serangan pengulangan, jenis serangan siber di mana penyerang mencegat dan mengirim ulang data untuk mendapatkan akses tidak sah atau melakukan tindakan berbahaya, penting untuk membandingkan nilai cap waktu yang diekstrak dengan cap waktu saat ini dan memastikan bahwa itu jatuh dalam batas waktu yang wajar. Sebagai contoh, 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 field tetap dan variabel. Ini memastikan bahwa data yang ditransmisikan dalam payload terstruktur dan konsisten, memudahkan aplikasi penerima untuk memproses dan menggunakan data tersebut.

Field skema payload tetap dapat membantu menjaga konsistensi di seluruh permintaan webhook, dengan field berikut 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 yang memicu notifikasi.
3. EventTime (string): Cap waktu kapan peristiwa dipicu.

Field 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 dari 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 yang Dapat Diidentifikasi Secara Pribadi (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 dalam Discord yang menggunakan API Cloud Terbuka untuk penyimpanan data untuk menghapus data PII sebagai solusi otomatisasi. Contoh ini dapat diadaptasi untuk menangani notifikasi lain, seperti peristiwa langganan.

Jika Anda menggunakan endpoint kustom sebagai server webhook Anda alih-alih alat pihak ketiga, Anda dapat mengekstrak data yang tunduk pada penghapusan dari payload webhook dan membangun solusi otomatisasi Anda sendiri. Contoh kode berikut adalah contoh server yang memiliki pencegahan terhadap serangan pengulangan dengan memverifikasi cap waktu dan bahwa permintaan tersebut 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 cap waktu dan tanda tangan 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');
   }

   // Validasikan 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');
});