Notifiche di webhook

Invece di monitorare manualmente tutti gli eventi nella tua esperienza e le richieste degli utenti, puoi configurare 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 flusso di lavoro di gestione delle notifiche per ridurre le notifiche di sforzo manuale.

Al momento, Roblox supporta completamente le notifiche webhook per Discord, Guilded e Slack.L'utilizzo di webhook con altri strumenti di terze parti comporta il rischio di non ricevere tutte le notifiche.

Workflow 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 configurare 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 il trattamento dei dati in tempo reale.

Una volta che hai configurato 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 al punto di destinazione personalizzato, che può agire in base ai dati inclusi nel payload del webhook.Questo potrebbe includere la cancellazione 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 evento.

Abbonamento

Abbonamento riassunto - Quando un utente si riabbonisce a un abbonamento, viene inviato un messaggio contenente l'abbonamento e l'utente.
Abbonamento rinnovato - Quando un utente rinnova un abbonamento, viene inviato un messaggio contenente l'abbonamento e l'utente.
Abbonamento rimborsato - Quando un utente riceve un rimborso per il proprio abbonamento, viene inviato un messaggio contenente l'abbonamento e l'utente.
Abbonamento acquistato - Quando un utente acquista un abbonamento, viene inviato un messaggio contenente l'abbonamento e l'utente.
Iscrizione annullata - Quando un utente annulla un'iscrizione, viene inviato un messaggio contenente l'iscrizione e l'iscritto, oltre al motivo fornito per l'annullamento.

Per ulteriori informazioni sugli eventi di sottoscrizione e sui loro campi, vedi il riferimento Sottoscrizione.

Conformità

Diritto di richiesta di cancellazione - Quando un utente invia una richiesta di cancellazione dei dati ai sensi del Regolamento generale sulla protezione dei dati (GDPR).

Commercio

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

Configura i webhook sulla dashboard di Creator

Per ricevere le notifiche attraverso i webhook, devi configurare un webhook che si abboni a determinati eventi per l'invio di notifiche.Per le esperienze di proprietà del gruppo, solo i proprietari del gruppo possono configurare e ricevere notifiche webhook.

Se stai configurando webhook e trattando dati personali, assicurati che rispettino il Regolamento generale sulla protezione dei dati (GDPR).

Per configurare un webhook:

Vai alla sezione Webhook della Dashboard del Creatore.
Fai clic sul pulsante Aggiungi Webhook .
Completa i campi di configurazione:
1. URL Webhook - Specifica l'URL in cui ricevere le notifiche.Per maggiori informazioni sui requisiti, vedi Imposta gli URL del webhook.
2. Nome - Usa un nome personalizzato per differenziare la tua configurazione da altre. Per impostazione predefinita, il valore è lo stesso dell'URL Webhook.
3. Segreto (opzionale) - Fornisci un segreto se vuoi verificare che le notifiche che ricevi provengono da Roblox.Per ulteriori informazioni, vedi Verifica la sicurezza del webhook.
4. Trigger - Scegli una o più opzioni dalla lista di trigger supportati di eventi per i quali vuoi ricevere notifiche.
Fai clic sul pulsante Salva modifiche .

Al momento, puoi configurare fino a 5 webhook in totale.

Configura gli URL del webhook

Puoi configurare un endpoint del servizio HTTP personalizzato come URL del webhook, a patto che soddisfi i seguenti requisiti:

Deve essere pubblicamente accessibile per gestire le richieste.
Può gestire le richieste POST.
Può rispondere alla richiesta con una risposta 2XX entro 5 secondi.
Può gestire le richieste HTTPS.

Quando il tuo endpoint riceve una richiesta POST, deve essere in grado di:

Estrai i dettagli richiesti sulla notifica dal corpo del messaggio POST.
Leggi il corpo del messaggio POST con i dettagli generici sulla notifica e dettagli specifici relativi al tipo di evento nella notifica.

Per ulteriori informazioni dello schema delle richieste POST da gestire, vedi il Schema di carico.

Politica di ripristino del fallimento della consegna

Quando una notifica webhook non riesce a raggiungere l'URL specificato a causa di errori come l'indisponibilità del punto di interfaccia, Roblox riprova l'invio del messaggio all'URL configurato 5 volte utilizzando una dimensione finestra fissa.Se la notifica non viene ancora consegnata dopo 5 tentativi, Roblox smette di inviare la notifica e suppone che l'URL non sia più valido.In questa situazione, è necessario aggiornare la configurazione del webhook con un nuovo URL raggiungibile e in grado di ricevere notifiche.Per risolvere i problemi e confermare che il tuo URL del webhook può ricevere con successo le notifiche, vedi 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 di webhook.Puoi trovare questi requisiti cercando la parola chiave "webhook" sul sito di supporto o di documentazione del tool target.Per gli strumenti terzi supportati di tre, vedi quanto segue:

Testa i webhook

Puoi testare se il webhook che hai configurato può ricevere con successo le notifiche sulla Dashboard del Creatore:

Vai alla pagina di configurazione Webhooks.
Seleziona il webhook che vuoi testare dall'elenco dei webhook configurati.
Fai clic sull'icona della matita accanto al webhook target.
Fai clic sul pulsante Risposta del test .

Il sistema poi invia un evento SampleNotification , che include l'ID utente dell'utente che ha attivato la notifica , come mostrato qui:

Schema di notifica di esempio
{
  "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 può ricevere con successo le notifiche dal tuo webhook.Se fornisci un segreto durante la configurazione del webhook, genera anche un roblox-signature che puoi utilizzare per testare la logica roblox-signature.

Verifica la sicurezza del webhook

Dopo aver configurato il tuo server per ricevere i carichi, inizia a ascoltare qualsiasi carico inviato all'endpoint.Se impostate un segreto durante la configurazione del webhook, Roblox invia un roblox-signature in ogni notifica webhook per garantire che la richiesta provenga effettivamente da Roblox.La firma è nell'intestazione del payload per i punti finali personalizzati e nel footer per i server di terze parti.

Signature format with a secret for custom endpoints
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:

Signature format without a secret for custom endpoints
t=<timestamp>

Per verificare una firma:

Estrai i valori timestamp e firma.Tutte le firme per i webhook con segreti condividono lo stesso formato di una stringa CSV con questi due valori seguiti dai prefissi:
- t : L'timestamp di quando è stata inviata la notifica.
- v1 : Il valore di firma generato utilizzando il segreto fornito dalla configurazione della dashboard del Creatore.
Ricrea la stringa di base di roblox-signature concatenando:
1. L'timestamp come stringa.
2. Il personaggio del periodo . .
3. La stringa JSON del corpo della richiesta.
Calcola un codice di autenticazione del messaggio basato sull'hash (HMAC) con la funzione hash SHA256 utilizzando il segreto che hai definito durante la configurazione come chiave e la stringa di base che hai generato attraverso il passo 2 come messaggio.Converti il risultato al formato Base64 per ottenere la firma prevista.
Confronta il valore della firma estratto con il valore della firma previsto. Se hai generato la firma correttamente, il valore dovrebbe essere lo stesso.
(Opzionale) Per prevenire gli attacchi di riproduzione, un tipo di attacco informatico in cui gli attaccanti intercettano e riinviano i dati per ottenere un accesso non autorizzato o eseguire azioni maliziose, è utile confrontare il valore dell'timestamp estratto con l'timestamp attuale 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 carico

Quando viene attivato l'evento target del tuo webhook, invia una richiesta al tuo URL del webhook, incluse 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 di schema di carico fissi possono aiutare a mantenere la coerenza in tutte le richieste di webhook, con i seguenti campi disponibili:

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

Il campo di carico variabile fornisce flessibilità per i webhook per ospitare diversi tipi di eventi, che includono:

EventPayload (oggetto): Contiene informazioni specifiche per il EventType che ha attivato il webhook.La struttura dello schema EventPayload varia a seconda del tipo di evento.

L'esempio seguente mostra lo schema di payload della richiesta Diritto all'oblio evento:

Schema di esempio per una richiesta di diritto all'oblio
{
   "NotificationId": "string",
   "EventType": "RightToErasureRequest",
   "EventTime": "2023-12-30T16:24:24.2118874Z",
   "EventPayload": {
      "UserId": 1,
      "GameIds": [
         1234, 2345
      ]
   }
}

Maneggiare le notifiche

Se memorizzi qualsiasi Informazione personalmente identificabile (PII) dei tuoi utenti, come i loro ID utente, devi eliminare queste informazioni quando un utente invia una tale richiesta per rispettare i requisiti di conformità al GDPR diritto all'oblio.Puoi creare un bot per gestire le notifiche di webhook e aiutare a automatizzare la cancellazione dei dati, a patto di archiviare PII in un deposito di dati.Vedi Automatizzazione delle richieste di cancellazione dei diritti per un esempio su come creare un bot all'interno di Guilded o Discord che utilizza l'Open Cloud API per i depositi di dati per eliminare i dati PII come soluzione di automazione.Questo esempio può essere adattato per gestire altre notifiche, come eventi di iscrizione.

Se utilizzi un endpoint personalizzato come server webhook invece di uno strumento di terze parti, puoi estrarre i dati soggetti a cancellazione dal payload webhook e costruire la tua soluzione di automazione.Il seguente esempio di codice è un esempio di server che ha la prevenzione dagli attacchi di riproduzione verificando l'timestamp e che la richiesta provenga da Roblox:

Extracting PII from Payload
const crypto = require('crypto');
const express = require('express');

const secret = '<your_secret>' // This can be set as an environment variable

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

app.all('/*', function (req, res) {
   console.log('New request recieved');

   // Extract the timestamp and signature from 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);

   // Ensure the request came within a 300 second window to prevent replay attacks
   const requestTimestampMs = timestamp * 1000;
   const windowTimeMs = 300 * 1000;
   const oldestTimestampAllowed = Date.now() - windowTimeMs;

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

   // Validate signature
   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('Unauthorized Request');
   }

   // Your logic to handle payload
   const payloadBody = req.body;
   const eventType = payloadBody['EventType'];

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

      console.log(`Payload data: UserId=${userId} and GameIds=${gameIds}`);
      // If you store PII in data stores, use the UserId and GameIds to delete the information from data stores.
   }

   return res.json({ message: 'Processed the message successfully' });
});

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

Su questa pagina