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.

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 Fornire.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 RGPD, l'invio di una conferma all'utente o l'attivazione di un altro evento.

Trigger supportati

Roblox attualmente supporta i seguenti trigger di evento per le notifiche:

• 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.
• Abbonamento acquistato - Quando un utente acquista 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 rinnovato - Quando un utente rinnova un abbonamento, viene inviato un messaggio contenente l'abbonamento e l'utente.
• Abbonamento riassunto - Quando un utente si riabbonisce a un abbonamento, viene inviato un messaggio contenente l'abbonamento e l'utente.
• "Diritto di essere dimenticato" richieste di cancellazione dei dati ai sensi del Regolamento generale sulla protezione dei dati ( GDPR ).

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

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.

Per configurare un webhook:

1. Vai alla sezione Webhooks della Dashboard del Creatore.
2. Fai clic sul pulsante Aggiungi Webhook .
3. Completa i campi di configurazione:

   1. URL Webhook — Specifica l'URL in cui ricevere le notifiche e accettare gli URL Webhook in arrivo da entità di terze parti.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.
4. Fai clic sul pulsante Salva modifiche .

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 RichiestaPOST, deve essere in grado di:

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

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

Politca Privacydi 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 strumentotarget.Per gli strumenti terzi supportati di tre, vedi quanto Seguendo:

• Centro d'assistenza Discord
• Supporto guidato
• Referenza API di Slack

Testa i webhook

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

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

Il sistema invia quindi una notifica nel inserisci / scrivi, che include l'ID utente dell'utente che attiva la Notifiche, come mostra lo schema di esempio seguente:

Schema di notifica di esempio
Body: {
  "NotificationId": "string",
  "EventType": "SampleNotification",
  "EventTime": "2023-12-30T16:24:24.2118874Z", // Tipo: Timbro ISO 8601
  "EventPayload": {
    "UserId": 1 // Tipo: Lungo
  }
}

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

Una volta che configuri 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 insieme a ogni notifica webhook per aiutare a proteggere la sicurezza dei dati.In questo modo, puoi usare l'it per verificare che la notifica provenga da Roblox e limitare il tuo server a ricevere solo richieste provenienti 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 Secret for Custom Endpoints
"roblox-signature": "t=<timestamp>,v1=<signature>"

Se non hai un segreto per il tuo webhook, la firma che ricevi contiene solo il valore timestamp quando viene inviata la notifica:

Signature Format without Secret for Custom Endpoints
"roblox-signature": "t=<timestamp>"

Per verificare una firma:

1. 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 : Il valore dell'timestamp quando viene inviata la notifica.
   • v1 : Il valore di firma generato utilizzando il segreto fornito dalla configurazione della dashboard del Creatore.Puoi estrarre questi due valori utilizzando la funzione split(), che separa la stringa in base a un delimitatore, in questo caso, il personaggio ,.

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

3. Calcola un codice di autenticazione del messaggio basato su Hash (HMAC) con la funzione di 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.

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

5. (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:

1. NotificationId , string : Un identificatore univoco per ogni notifica inviata. Se lo stesso NotificationId viene ricevuto due volte, viene considerato duplicato.
2. EventType , string : Una stringa rappresenta il tipo di evento per il quale è stata attivata la notifica.
3. EventTime , timestamp : Un timestamp approssimativo che indica quando è stato attivato l'evento.

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

1. EventPayload , object : 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 dell'evento Diritto di richiesta di cancellazione :

Schema di esempio per richiesta di diritto all'oblio
Body:{

   "NotificationId": "string",

   "EventType": "RightToErasureRequest",

   "EventTime": "2023-12-30T16:24:24.2118874Z",

   "EventPayload": {

      "UserId": 1, // Tipo: Lungo

      "GameIds": [ // Tipo: un array di Longs

         1234, 2345

      ]

   }

}

Maneggiare le notifiche

Se memorizzi qualsiasi Informazione personalmente identificabile (Informazioni di identificazione personale (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 Negoziodi 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 fornisce una soluzione di esempio e aggiunge la prevenzione agli attacchi di riproduzione verificando che la richiesta provenga da Roblox:

Extracting PII from Payload
const crypto = require('crypto')
const express = require('express');
let app = express();
app.use(express.json());
app.use(express.urlencoded({ extended: true }));
// This is a sample only code
app.all('/*', function (req, res) {
   console.log('-------- New Request Seen -------');
   // 1. Extract the timestamp and signature
   const shared_secret = '<Your secret>' // This can be set as an environment variable
   const hmac = crypto.createHmac('sha256', shared_secret)
   const roblox_signature_header = req.headers['roblox-signature'].split(',')
   // 'roblox-signature' is present in all requests:
   // Timestamp(t) is present in all requests, however signature value(v1) is not set unless a secret is shared during the webhook configuration.
   // Fetch header component at Index 0 -> 't=' and Index 1 -> 'v1='
   const timestamp = roblox_signature_header.find(e => e.startsWith('t=')).substring(2);
   const extracted_signature = roblox_signature_header.find(e => e.startsWith('v1='));
   // 2. Prevent Replay attack: 300 seconds window
   const request_timestamp_ms = timestamp * 1000;
   const window_time_ms = 300 * 1000
   const oldest_timestamp_allowed = Date.now() - window_time_ms;
   if (request_timestamp_ms < oldest_timestamp_allowed) {
      res.status(403).send('Expired Request')
   }
   // 3. Validate Signature
   if (extracted_signature !== undefined) {
      const signature_v1 = extracted_signature.substring(3);
      const message = `${timestamp}.${JSON.stringify(req.body)}`
      const base64_signature = hmac.update(message).digest('base64')
      if (signature_v1 !== base64_signature) {
         res.status(401).send('Unauthorized Request')
      }
   }
   // 4. 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']
      const gameIdString = gameIds.toString()
      console.log(`The payload: UserId=${userId} and GameIds=${gameIdString}`)
      // If you store PII in data stores, use the UserId and GameIds to make a data store call to delete the information.
   }
   // 5. Return Response
   res.json({ message: 'Processed the message Successfully' });
})
app.listen(8080, function () {
   console.log('This is a Sample application')
})