Invece di monitorare manualmente tutti gli eventi nel tuo gioco e le richieste degli utenti, puoi impostare i webhook per ricevere notifiche in tempo reale su uno strumento di messaggistica di terze parti o sul tuo endpoint personalizzato in grado di ricevere richieste HTTP. Questo ti aiuta ad automatizzare il tuo flusso di lavoro nella gestione delle notifiche per ridurre lo sforzo manuale nella gestione delle notifiche.
Attualmente, Roblox supporta completamente le notifiche webhook per Discord e Slack. Utilizzare webhook con altri strumenti di terze parti comporta il rischio di non ricevere tutte le notifiche.
Flusso di lavoro del webhook
I webhook inviano notifiche o dati in tempo reale tra due diverse applicazioni o servizi, come Roblox e uno strumento di messaggistica di terze parti. A differenza delle API tradizionali, che richiedono di impostare un'app client per inviare richieste a un server per ricevere dati, i webhook inviano dati al tuo endpoint client non appena si verifica un evento. Sono utili per automatizzare i flussi di lavoro tra Roblox e le applicazioni di terze parti che utilizzi per collaborare con il tuo team, in quanto consentono la condivisione e l'elaborazione dei dati in tempo reale.
Una volta che hai impostato un webhook, ogni volta che si verifica un evento target, Roblox invia una richiesta all'URL del webhook che fornisci. L'URL del webhook poi reindirizza la richiesta alla tua applicazione ricevente o all'endpoint personalizzato, che può intraprendere un'azione basata sui dati inclusi nel payload del webhook. Questo potrebbe includere l'eliminazione dei dati per il GDPR, l'invio di una conferma all'utente o l'attivazione di un altro evento.
Trigger supportati
Roblox attualmente supporta i seguenti trigger di eventi.
Abbonamento
- Abbonamento Rinnovo - Quando un utente rinnova un abbonamento, viene inviato un messaggio contenente l'abbonamento e l'abbonato.
- Abbonamento Rinnovato - Quando un utente rinnova un abbonamento, viene inviato un messaggio contenente l'abbonamento e l'abbonato.
- Abbonamento Rimborsato - Quando un utente riceve un rimborso per il proprio abbonamento, viene inviato un messaggio contenente l'abbonamento e l'abbonato.
- Abbonamento Acquistato - Quando un utente acquista un abbonamento, viene inviato un messaggio contenente l'abbonamento e l'abbonato.
- Abbonamento Annullato - Quando un utente annulla un abbonamento, viene inviato un messaggio contenente l'abbonamento e l'abbonato, nonché il motivo fornito per l'annullamento.
Per ulteriori informazioni sugli eventi di abbonamento e i loro campi, consulta il riferimento Abbonamento.
Conformità
- Richiesta di Diritto all'Eliminazione - Quando un utente presenta una richiesta di eliminazione dei dati ai sensi del Regolamento Generale sulla Protezione dei Dati (GDPR).
Commercio
- Ordine di Prodotto Commerciale Rimborsato - Quando un utente ha ricevuto un rimborso per il proprio ordine di prodotto commerciale, oppure l'ordine è stato annullato.
- Ordine di Prodotto Commerciale Pagato - Quando un utente ha pagato il proprio ordine di prodotto commerciale. Si prega di notare che eventi webhook duplicati sono possibili, quindi è necessario deduplicare gli eventi utilizzando l'ID ordine commerciale unico.
Configurare i webhook nel Creator Dashboard
Per ricevere notifiche tramite webhook, è necessario configurare un webhook che si iscrive a determinati eventi per attivare le notifiche. Per i giochi di proprietà di gruppo, solo i proprietari del gruppo possono configurare e ricevere notifiche webhook.
Se stai impostando i webhook e gestendo dati personali, assicurati che siano conformi al Regolamento Generale sulla Protezione dei Dati (GDPR).
Per impostare un webhook:
Seleziona la tua esperienza su Creator Hub.
Sotto Configura, seleziona Webhook e fai clic su Aggiungi Webhook.
L'URL del webhook proviene dal tuo fornitore. Ad esempio, un URL di Slack probabilmente appare così:
https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXXInserisci il tuo URL del webhook e un nome.
(Facoltativo) Includi un segreto, che aiuta a garantire che le notifiche che ricevi provengano da Roblox. Per ulteriori informazioni, consulta Verificare la sicurezza del webhook.
Scegli una o più opzioni dall'elenco dei trigger supportati di eventi per cui desideri ricevere notifiche.
(Facoltativo) Utilizza il pulsante Testa Risposta per controllare se il tuo servizio può ricevere una richiesta di esempio.
Fai clic su Salva Modifiche.
Attualmente, puoi configurare fino a 5 webhook in totale.
Impostare gli URL dei webhook
Puoi impostare un endpoint di servizio HTTP personalizzato come URL del tuo webhook, a condizione che soddisfi i seguenti requisiti:
- Deve essere accessibile pubblicamente per gestire le richieste.
- Deve gestire le richieste POST.
- Deve rispondere alla richiesta con una risposta 2XX entro 5 secondi.
- Deve gestire richieste HTTPS.
Quando il tuo endpoint riceve una richiesta POST, deve essere in grado di:
- Estrarre i dettagli richiesti sulla notifica dal corpo del messaggio POST.
- Leggere il corpo del messaggio POST con i dettagli generali sulla notifica e i dettagli specifici relativi al tipo di evento riguardante la notifica.
Per ulteriori informazioni sullo schema delle richieste POST da gestire, consulta lo Schema Payload.
Politica di retry in caso di fallimento della consegna
Quando una notifica webhook non riesce a raggiungere l'URL specificato a causa di errori come l'indisponibilità dell'endpoint, Roblox riprova a inviare il messaggio all'URL configurato 5 volte utilizzando una finestra di tempo fissa. Se la notifica continua a non essere consegnata dopo 5 tentativi, Roblox smette di cercare di inviare la notifica e presume che l'URL non sia più valido. In questa situazione, è necessario aggiornare la configurazione del webhook con un nuovo URL che sia raggiungibile e in grado di ricevere notifiche. Per risolvere i problemi e confermare che il tuo URL del webhook possa ricevere correttamente notifiche, consulta Testare i webhook.
Requisiti di terze parti
Gli strumenti di terze parti di solito hanno i propri requisiti per i webhook che devi seguire quando imposti l'URL del tuo webhook. Puoi trovare questi requisiti cercando la parola chiave "webhook" nel sito di supporto o nella documentazione dello strumento di destinazione. Per gli strumenti di terze parti supportati, consulta i seguenti link:
Testare i webhook
Puoi testare se il webhook che hai configurato può ricevere correttamente notifiche nel Creator Dashboard:
- Naviga nella pagina di configurazione Webhook.
- Seleziona il webhook che desideri testare dall'elenco dei webhook configurati.
- Fai clic sull'icona della matita accanto al webhook di destinazione.
- Fai clic sul pulsante Testa Risposta.
Il sistema invia quindi un evento SampleNotification, che include l'ID Utente dell'utente che ha attivato la notifica, come mostrato di seguito:
Schema SampleNotification
{
"NotificationId": "string",
"EventType": "SampleNotification",
"EventTime": "2023-12-30T16:24:24.2118874Z",
"EventPayload": {
"UserId": 1
}
}
Se stai integrando il tuo webhook con un servizio di terze parti, puoi testarlo utilizzando l'URL di terze parti per confermare che il servizio possa ricevere correttamente notifiche dal tuo webhook. Se fornisci un segreto durante la configurazione del webhook, genera anche una roblox-signature che puoi utilizzare per testare la logica roblox-signature.
Verificare la sicurezza del webhook
Dopo aver configurato il tuo server per ricevere i payload, inizia ad ascoltare tutti i payload inviati all'endpoint. Se hai impostato un segreto durante la configurazione del tuo webhook, Roblox invia una roblox-signature in ciascuna notifica webhook per garantire che la richiesta provenga effettivamente da Roblox. La firma è nell'intestazione del payload per gli endpoint personalizzati e nel footer per i server di terze parti.
Formato della firma con un segreto per gli endpoint personalizzati
Se non hai impostato un segreto per il tuo webhook, la firma contiene solo il timestamp di quando è stata inviata la notifica:
Formato della firma senza un segreto per gli endpoint personalizzati
t=<timestamp>
Per verificare una firma:
Estrai i valori timestamp e firma. Tutte le firme per i webhook con segreti condividono lo stesso formato come stringa CSV con questi due valori seguiti dai prefissi:
- t: Il timestamp di quando è stata inviata la notifica.
- v1: Il valore della firma generato utilizzando il segreto fornito dalla configurazione del Creator Dashboard.
Ricrea la stringa di base di roblox-signature concatenando:
- Il timestamp come stringa.
- Il carattere punto ..
- La stringa JSON del corpo della richiesta.
Calcola un codice di autenticazione basato su hash (HMAC) utilizzando la funzione di hash SHA256 con il segreto che hai definito durante la configurazione come chiave e la stringa di base che hai generato tramite il passaggio 2 come messaggio. Converti il risultato in formato Base64 per ottenere la firma attesa.
Confronta il valore della firma estratto con la firma attesa. Se hai generato correttamente la firma, il valore dovrebbe essere lo stesso.
(Facoltativo) Per prevenire attacchi di replay, un tipo di attacco informatico in cui gli attaccanti intercettano e reinviano i dati per ottenere accesso non autorizzato o per effettuare azioni dannose, è utile confrontare il valore del timestamp estratto con il timestamp corrente e garantire che rientri all'interno di un limite di tempo ragionevole. Ad esempio, una finestra di 10 minuti è di solito un buon limite di tempo ragionevole.
Schema del payload
Quando si attiva l'evento target del tuo webhook, invia una richiesta al tuo URL del webhook, includendo informazioni sull'evento nel payload. Tutti i payload delle richieste condividono lo stesso schema che consiste in campi fissi e variabili. Questo garantisce che i dati trasmessi nel payload siano strutturati e coerenti, rendendo più facile per l'applicazione ricevente elaborare e utilizzare i dati.
I campi dello schema del payload fisso possono aiutare a mantenere la coerenza tra tutte le richieste webhook, con i seguenti campi disponibili:
- NotificationId (string): Un identificatore univoco per ciascuna notifica inviata. Se viene ricevuto lo stesso NotificationId due volte, viene considerato un duplicato.
- EventType (string): Indica il tipo di evento per il quale è stata attivata la notifica.
- EventTime (string): Il timestamp di quando è stato attivato l'evento.
I campi dello schema del payload variabile offrono flessibilità per i webhook in modo da adattarsi a vari tipi di eventi, che includono:
- EventPayload (oggetto): Contiene informazioni specifiche sul EventType che ha attivato il webhook. La struttura dello schema di EventPayload varia in base al tipo di evento.
Il seguente esempio mostra lo schema del payload per l'evento Richiesta di Diritto all'Eliminazione:
Schema esempio per una richiesta di Diritto all'Eliminazione
{
"NotificationId": "string",
"EventType": "RightToErasureRequest",
"EventTime": "2023-12-30T16:24:24.2118874Z",
"EventPayload": {
"UserId": 1,
"GameIds": [
1234, 2345
]
}
}
Gestire le notifiche
Se archivi qualsiasi Informazione Personale Identificabile (PII) dei tuoi utenti, come i loro ID Utente, devi eliminare queste informazioni quando un utente presenta una richiesta del genere per rispettare i requisiti di conformità GDPR sul diritto all'eliminazione. Puoi creare un bot per gestire le notifiche webhook e aiutare ad automatizzare l'eliminazione dei dati, a condizione che tu stia archiviando PII in un data store. Consulta Automazione dell'Eliminazione delle Richieste di Diritto all'Eliminazione per un esempio su come creare un bot all'interno di Discord che utilizza l'Open Cloud API per i data store per eliminare i dati PII come soluzione di automazione. Questo esempio può essere adattato per gestire altre notifiche, come gli eventi di abbonamento.
Se utilizzi un endpoint personalizzato come server webhook invece di uno strumento di terze parti, puoi estrarre i dati soggetti a eliminazione dal payload del webhook e costruire la tua soluzione di automazione. Il seguente esempio di codice è un esempio di un server che ha una prevenzione contro gli attacchi di replay verificando il timestamp e che la richiesta proviene da Roblox:
Estrazione PII dal Payload
const crypto = require('crypto');
const express = require('express');
const secret = '<tuo_segreto>' // Questo può essere impostato come una variabile di ambiente
let app = express();
app.use(express.json());
app.all('/*', function (req, res) {
console.log('Nuova richiesta ricevuta');
// Estrai il timestamp e la firma dall'intestazione
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);
// Assicurati che la richiesta sia avvenuta entro una finestra di 300 secondi per prevenire attacchi di replay
const requestTimestampMs = timestamp * 1000;
const windowTimeMs = 300 * 1000;
const oldestTimestampAllowed = Date.now() - windowTimeMs;
if (requestTimestampMs < oldestTimestampAllowed) {
return res.status(403).send('Richiesta Scaduta');
}
// Valida la firma
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('Richiesta Non Autorizzata');
}
// La tua logica per gestire il payload
const payloadBody = req.body;
const eventType = payloadBody['EventType'];
if (eventType === 'RightToErasureRequest'){
const userId = payloadBody['EventPayload']['UserId'];
const gameIds = payloadBody['EventPayload']['GameIds'];
console.log(`Dati del payload: UserId=${userId} e GameIds=${gameIds}`);
// Se archivi PII nei data store, utilizza l'UserId e i GameIds per eliminare le informazioni dai data store.
}
return res.json({ message: 'Messaggio elaborato con successo' });
});
app.listen(8080, function () {
console.log('Server avviato');
});