Notifiche Webhook

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 che può ricevere richieste HTTP. Questo ti aiuta ad automatizzare il tuo flusso di lavoro di gestione delle notifiche per ridurre lo sforzo manuale nella gestione delle notifiche.

Flusso di lavoro dei 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'applicazione 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, poiché consentono la condivisione e l'elaborazione dei dati in tempo reale.

Una volta 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 reindirizza quindi la richiesta alla tua applicazione ricevente o al tuo endpoint personalizzato, che può intraprendere azioni in base ai dati inclusi nel payload del webhook. Questo potrebbe includere l'eliminazione dei dati per la conformità al RTBF, 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 Rinnovato - Quando un utente rinnova un abbonamento, viene inviata un messaggio contenente l'abbonamento e l'abbonato.
• Abbonamento Rinnovato - Quando un utente rinnova un abbonamento, viene inviata un messaggio contenente l'abbonamento e l'abbonato.
• Abbonamento Rimborsato - Quando un utente riceve un rimborso per il proprio abbonamento, viene inviata un messaggio contenente l'abbonamento e l'abbonato.
• Abbonamento Acquistato - Quando un utente acquista un abbonamento, viene inviata un messaggio contenente l'abbonamento e l'abbonato.
• Abbonamento Annullato - Quando un utente annulla un abbonamento, viene inviata un messaggio contenente l'abbonamento e l'abbonato, oltre al motivo fornito per l'annullamento.

Per ulteriori informazioni sugli eventi di abbonamento e sui loro campi, consulta il riferimento Abbonamento.

Conformità

• Diritto all'Eliminazione / Richiesta di Cancellazione - Quando un utente esercita il proprio diritto di avere le proprie informazioni personali eliminate permanentemente ai sensi delle normative globali sulla protezione dei dati e sulla privacy applicabili. Maggiori informazioni possono essere trovate in RTBF e Creatori.

Commercio

• Ordine Prodotto Commerciale Rimborsato - Quando un utente ha ricevuto un rimborso per il proprio ordine di prodotto commerciale, o l'ordine è stato annullato.
• Ordine Prodotto Commerciale Pagato - Quando un utente ha pagato per il proprio ordine di prodotto commerciale. Si prega di notare che eventi webhook duplicati sono possibili, quindi dovresti deduplicare gli eventi utilizzando l'ID ordine commerciale unico.

Configura i webhook nel Creator Dashboard

Per ricevere notifiche tramite webhook, devi configurare un webhook che si iscriva a determinati eventi per attivare notifiche. Per i giochi di proprietà di un gruppo, solo i proprietari del gruppo possono configurare e ricevere notifiche webhook.

Per impostare un webhook:

1. Seleziona la tua esperienza su Creator Hub.

2. 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/XXXXXXXXXXXXXXXXXXXXXXXX

3. Inserisci il tuo URL del webhook e un nome.

4. OPZIONALE

   Includi un segreto, che aiuta a garantire che le notifiche che ricevi provengano da Roblox. Per ulteriori informazioni, consulta Verifica della sicurezza del webhook.

5. Scegli una o più opzioni dall'elenco dei trigger supportati di eventi per i quali desideri ricevere notifiche.

6. OPZIONALE

   Usa il pulsante Testa Risposta per controllare se il tuo servizio può ricevere una richiesta di esempio.

7. Fai clic su Salva Modifiche.

Imposta 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.
• Può gestire richieste POST.
• Può rispondere alla richiesta con una risposta 2XX entro 5 secondi.
• Può 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 sulla notifica.

Per ulteriori informazioni sullo schema delle richieste POST da gestire, consulta lo Schema del Payload.

Politica di ripetizione dei fallimenti di consegna

Quando una notifica webhook non riesce a raggiungere il tuo URL specificato a causa di errori come l'indisponibilità dell'endpoint, Roblox riprova a inviare il messaggio all'URL configurato 5 volte utilizzando una dimensione della finestra fissa. Se la notifica continua a non essere consegnata dopo 5 tentativi, Roblox smette di provare a inviare la notifica e presume che l'URL non sia più valido. In questa situazione, devi aggiornare la configurazione del tuo 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 le notifiche, consulta Testa 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 il tuo URL del webhook. Puoi trovare questi requisiti cercando la parola chiave "webhook" sul sito di supporto o documentazione dello strumento di destinazione. Per gli strumenti di terze parti supportati, consulta i seguenti:

• Centro Assistenza Discord
• Riferimento API Slack

Testa i webhook

Puoi testare se il webhook che hai configurato può ricevere correttamente le notifiche nel Creator Dashboard:

1. Naviga alla pagina di configurazione Webhook.
2. Seleziona il webhook che desideri testare dall'elenco dei webhook configurati.
3. Fai clic sull'icona della matita accanto al webhook target.
4. 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 qui:

{
  "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 le 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 della roblox-signature.

Verifica la sicurezza del webhook

Dopo aver configurato il tuo server per ricevere i payload, inizia ad ascoltare qualsiasi payload inviato all'endpoint. Se hai impostato un segreto durante la configurazione del tuo webhook, Roblox invia una roblox-signature in ogni notifica webhook per garantire che la richiesta provenga effettivamente da Roblox. La firma si trova nell'intestazione del payload per gli endpoint personalizzati e nel piè di pagina per i server di terze parti.

t=<timestamp>,v1=<signature>

Se non hai impostato un segreto per il tuo webhook, la firma contiene solo il timestamp di quando è stata inviata la notifica:

t=<timestamp>

Per verificare una firma:

1. Estrai i valori di 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.

2. Ricrea la stringa base di roblox-signature concatenando:

   1. Il timestamp come stringa.
   2. Il carattere di punto ..
   3. La stringa JSON del corpo della richiesta.

3. Calcola un codice di autenticazione del messaggio basato su hash (HMAC) con la funzione hash SHA256 utilizzando il segreto che hai definito durante la configurazione come chiave e la stringa base che hai generato attraverso il passo 2 come messaggio. Converti il risultato in formato Base64 per ottenere la firma attesa.

4. Confronta il valore della firma estratta con la firma attesa. Se hai generato correttamente la firma, il valore dovrebbe essere lo stesso.

5. OPZIONALE

   Per prevenire attacchi di ripetizione, un tipo di attacco informatico in cui gli aggressori intercettano e rinviano dati per ottenere accesso non autorizzato o eseguire azioni dannose, è utile confrontare il valore del timestamp estratto con il timestamp attuale e assicurarsi che rientri in un limite di tempo ragionevole. Ad esempio, una finestra di 10 minuti è solitamente un buon limite di tempo ragionevole.

Schema del payload

Quando l'evento target del tuo webhook viene attivato, 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, facilitando l'elaborazione e l'utilizzo dei dati da parte dell'applicazione ricevente.

I campi fissi dello schema del payload possono aiutare a mantenere la coerenza tra tutte le richieste webhook, con i seguenti campi disponibili:

1. NotificationId (stringa): Un identificatore unico per ogni notifica inviata. Se lo stesso NotificationId viene ricevuto due volte, è considerato un duplicato.
2. EventType (stringa): Indica il tipo di evento per il quale è stata attivata la notifica.
3. EventTime (stringa): Il timestamp di quando è stato attivato l'evento.

I campi variabili dello schema del payload forniscono flessibilità per i webhook per accogliere vari tipi di eventi, che includono:

1. EventPayload (oggetto): Contiene informazioni specifiche per il EventType che ha attivato il webhook. La struttura dello schema EventPayload varia in base al tipo di evento.

Il seguente esempio mostra lo schema del payload dell'evento Richiesta di Diritto all'Eliminazione:

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

Gestisci le notifiche

Se memorizzi qualsiasi Informazione Personale Identificabile (PII) dei tuoi utenti, come i loro ID Utente, dovresti valutare la richiesta alla luce dei tuoi obblighi legali. Maggiori informazioni possono essere trovate in RTBF e Creatori. Puoi creare un bot per gestire le notifiche webhook e aiutare ad automatizzare l'eliminazione dei dati, a condizione che tu stia memorizzando PII in un data store. Consulta Automatizzare l'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 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 prevenzione contro gli attacchi di ripetizione verificando il timestamp e che la richiesta provenga da Roblox:

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

const secret = '<your_secret>' // Questo può essere impostato come variabile d'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 ripetizione
   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 memorizzi 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');
});