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 nella gestione delle notifiche per ridurre gli sforzi manuali nella gestione delle notifiche.

Flusso di lavoro dei webhook

I webhook inviano notifiche o dati in tempo reale tra due applicazioni o servizi diversi, 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 configurato un webhook, ogni volta che si verifica un evento target, Roblox invia una richiesta all'URL del webhook fornito. L'URL del webhook quindi reindirizza la richiesta alla tua applicazione di ricezione o all'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.

Sottoscrizione

• Sottoscrizione Rinnovo - Quando un utente rinnova una sottoscrizione, viene inviato un messaggio contenente la sottoscrizione e l'abbonato.
• Sottoscrizione Rinnovata - Quando un utente rinnova una sottoscrizione, viene inviato un messaggio contenente la sottoscrizione e l'abbonato.
• Sottoscrizione Rimborsata - Quando un utente riceve un rimborso per la propria sottoscrizione, viene inviato un messaggio contenente la sottoscrizione e l'abbonato.
• Sottoscrizione Acquistata - Quando un utente acquista una sottoscrizione, viene inviato un messaggio contenente la sottoscrizione e l'abbonato.
• Sottoscrizione Annullata - Quando un utente annulla una sottoscrizione, viene inviato un messaggio contenente la sottoscrizione e l'abbonato, oltre al motivo fornito per l'annullamento.

Per ulteriori informazioni sugli eventi di sottoscrizione e i loro campi, consulta il riferimento alla Sottoscrizione.

Conformità

• Diritto all'Oblio / Richiesta di Eliminazione - Quando un utente esercita il proprio diritto a avere le proprie informazioni personali permanentemente eliminate in base alle normative globali sulla protezione e la privacy dei dati. Maggiori informazioni possono essere trovate in RTBF e Creatori.

Commercio

• Ordine Prodotto Commerciale Rimborsato - Quando un utente riceve 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 possono verificarsi eventi webhook duplicati, quindi dovresti deduplicare gli eventi utilizzando l'ID ordine commerciale unico.

Configura webhook nel Creator Dashboard

Per ricevere notifiche tramite webhook, devi configurare un webhook che si iscriva a determinati eventi per attivare le 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. (Facoltativo) Includi un segreto, che aiuta a garantire che le notifiche che ricevi provengano da Roblox. Per ulteriori informazioni, vedere Verifica della sicurezza del webhook.

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

6. (Facoltativo) Usa il pulsante Testa Risposta per verificare 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 tuo URL webhook, a condizione che soddisfi i seguenti requisiti:

• Deve essere pubblicamente accessibile per gestire le richieste.
• Deve essere in grado di gestire le richieste POST.
• Deve essere in grado di rispondere alla richiesta con una risposta 2XX entro 5 secondi.
• Deve essere in grado di gestire le 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, vedere lo Schema del Payload.

Politica di ripetizione degli errori di consegna

Quando una notifica webhook non riesce a raggiungere il tuo URL specificato a causa di errori come la non disponibilità dell'endpoint, Roblox prova a inviare il messaggio all'URL configurato 5 volte utilizzando una dimensione di finestra fissa. Se la notifica continua a non essere consegnata dopo 5 tentativi, Roblox smette di cercare di inviare la notifica e assume che l'URL non sia più valido. In questa situazione, devi aggiornare la tua 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 webhook possa ricevere correttamente le notifiche, vedere Testa webhook.

Requisiti di terze parti

Gli strumenti di terze parti di solito hanno i propri requisiti per i webhook che devi seguire quando configuri il tuo URL 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, vedere i seguenti:

• Centro Assistenza Discord
• Documentazione API Slack

Testa i webhook

Puoi testare se il webhook che hai configurato può ricevere correttamente 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 il User ID 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 della sicurezza del webhook

Dopo aver configurato il tuo server per ricevere i payload, inizia a 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 è 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 punto ..
   3. La stringa JSON del corpo della richiesta.

3. Calcola un codice di autenticazione di messaggi basato su hash (HMAC) utilizzando 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 di firma estratto con la firma attesa. Se hai generato correttamente la firma, il valore dovrebbe essere lo stesso.

5. (Facoltativo) Per prevenire attacchi di ripetizione, un tipo di attacco informatico in cui gli attaccanti intercettano e rinviano dati per ottenere accesso non autorizzato o compiere azioni malevole, è utile confrontare il valore di timestamp estratto con il timestamp corrente e assicurarsi che rientri in un limite di tempo ragionevole. Ad esempio, una finestra di 10 minuti è di solito un buon limite di tempo ragionevole.

Schema del Payload

Quando l'evento target del tuo webhook viene attivato, invia una richiesta al tuo URL webhook, includendo informazioni sull'evento nel payload. Tutti i payload delle richieste condividono lo stesso schema che consiste in campi fissi e variabili. Questo assicura che i dati trasmessi nel payload siano strutturati e coerenti, rendendo più facile per l'applicazione ricevente elaborare e utilizzare i dati.

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 univoco per ciascuna 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 offrono 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 di EventPayload varia in base al tipo di evento.

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

{
   "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 utenti, 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. Vedi Automatizzare l'eliminazione delle richieste di Diritto all'Oblio per un esempio di come creare un bot all'interno di Discord che utilizza l'Open Cloud API per data store per eliminare i dati PII come soluzione di automazione. Questo esempio può essere adattato per gestire altre notifiche, come eventi di sottoscrizione.

Se utilizzi un endpoint personalizzato come server webhook invece di uno strumento di terze parti, puoi estrarre i dati soggetti all'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 proviene 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 arrivi 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, usa l'ID utente e gli ID gioco per eliminare le informazioni dai data store.
   }

   return res.json({ message: 'Messaggio elaborato con successo' });
});

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