Webhook-Benachrichtigungen

Anstatt alle Ereignisse in deiner Erfahrung und Anfragen von Benutzern manuell zu überwachen, kannst du Webhooks einrichten, um Echtzeitbenachrichtigungen über ein Drittmessenger-Tool oder deinen benutzerdefinierten Endpunkt zu erhalten, der HTTP-Anfragen empfangen kann.Dies hilft Ihnen, Ihren Benachrichtigungsworkflow zu automatisieren, um die manuelle Bearbeitung von Benachrichtigungen zu reduzieren.

Derzeit unterstützt Roblox vollständig Webhook-Benachrichtigungen für Discord, Guilded und Slack.Die Verwendung von Webhooks mit anderen Drittwerkzeugen birgt das Risiko, nicht alle Benachrichtigungen zu erhalten.

Webhook-Arbeitsablauf

Webhooks senden Echtzeitbenachrichtigungen oder Daten zwischen zwei verschiedenen Anwendungen oder Diensten, wie Roblox und einem Drittmessenger-Tool.Im Gegensatz zu traditionellen APIs, die eine Client-Anwendung erfordern, um eine Anfrage an einen Server zu senden, um Daten zu empfangen, senden Webhooks Daten an Ihr Client-Endpunkt, sobald ein Ereignis auftritt.Sie sind nützlich für die Automatisierung von Workflows zwischen Roblox und Drittanwendungen, die du zum Zusammenarbeiten mit deinem Team verwendest, da sie eine Echtzeit-Datenfreigabe und -verarbeitung ermöglichen.

Sobald du einen Webhook eingerichtet hast, sendet Roblox jedes Mal, wenn ein Zielereignis auftritt, eine Anfrage an die von dir angebenWebhook-URL.Die Webhook-URL leitet die Anfrage dann auf Ihre empfangende Anwendung oder benutzerdefinierte Endpunkt um, die auf der Grundlage der in der Webhook-Payload enthaltenen Daten Maßnahmen ergreifen kann.Dies könnte die Löschung von Daten für die DSGVO umfassen, die Übermittlung einer Bestätigung an den Benutzer oder das Auslösen eines anderen Ereignisses.

Unterstützte Trigger

Roblox unterstützt derzeit die folgenden Ereignisknoten für Benachrichtigungen:

Abonnement abgebrochen - Wenn ein Benutzer ein Abonnement abbricht, wird eine Nachricht gesendet, die das Abonnement und den Abonnenten enthält, sowie den Grund für die Kündigung.
Abonnement gekauft - Wenn ein Benutzer ein Abonnement kauft, wird eine Nachricht mit dem Abonnement und dem Abonnenten gesendet.
Abonnement erstattet - Wenn ein Benutzer eine Rückerstattung für sein Abonnement erhält, wird eine Nachricht mit dem Abonnement und dem Abonnenten verschickt.
Abonnement verlängert - Wenn ein Benutzer ein Abonnement erneuert, wird eine Nachricht mit dem Abonnement und dem Abonnenten gesendet.
Abonnement wieder abonniert - Wenn ein Benutzer ein Abonnement wieder abonniert, wird eine Nachricht mit dem Abonnement und dem Abonnenten gesendet.
"Recht auf Vergessen" Datenlöschanfragen gemäß der Allgemeinen Datenschutzverordnung ( GDPR ).

Für weitere Informationen zu Abonnementereignissen und ihren Feldern siehe die Cloud-API-Abonnement Referenz.

Webhooks auf Creator-Dashboard konfigurieren

Um Benachrichtigungen durch Webhooks zu erhalten, musst du einen Webhook konfigurieren, der sich für bestimmte Ereignisse abonniert, um Benachrichtigungen auszulösen.Für gruppeneigene Erlebnisse können nur Gruppenbesitzer Webhook-Benachrichtigungen konfigurieren und empfangen.

Wenn du Webhooks einrichtest und personenbezogene Daten verarbeitest, stelle sicher, dass sie der Allgemeinen Datenschutzverordnung (DSGVO) entsprechen.

Um einen Webhook einzurichten:

Navigiere zum Webhooks-Abschnitt des Creator-Dashboards.
Klicken Sie auf die Schaltfläche Webhook hinzufügen .
Fülle die Konfigurationsfelder aus:
1. Webhook-URL — Gib die URL an, über die du Benachrichtigungen empfangen und eingehende Webhook-URLs von Drittentitäten akzeptieren möchtest.Für weitere Informationen zu den Anforderungen siehe Einrichtung von Webhook-URLs.
2. Name — Verwende einen benutzerdefinierten Namen, um deine Konfiguration von anderen zu unterscheiden. Standardmäßig ist der Wert der gleiche wie die Webhook-URL.
3. Geheim (optional) — Liefern Sie ein Geheimnis, wenn Sie überprüfen möchten, dass Benachrichtigungen, die Sie erhalten, von Roblox stammen.Für weitere Informationen, siehe Überprüfen der Webhook-Sicherheit.
4. Trigger — Wählen Sie eine oder mehrere Optionen aus der Liste der unterstützten Trigger von Ereignissen, für die Sie Benachrichtigungen erhalten möchten.
Klicken Sie auf die Schaltfläche Änderungen speichern .

Derzeit kannst du insgesamt bis zu 5 Webhooks konfigurieren.

Webhook-URLs einrichten

Du kannst einen benutzerdefinierten HTTP-Service-Endpunkt als deine Webhook-URL einrichten, vorausgesetzt, er erfüllt die folgenden Anforderungen:

Es muss öffentlich zugänglich sein, um Anfragen zu bearbeiten.
Es kann POST-Anfragen bearbeiten.
Es kann auf die Anfrage mit einer 2XX-Antwort innerhalb von 5 Sekunden antworten.
Es kann HTTPS-Anfragen bearbeiten.

Wenn Ihr Endpunkt eine POST-Anfrage erhält, muss er in der Lage sein:

Extrahiere die erforderlichen Details über die Benachrichtigung aus dem Körper der POST-Nachricht.
Lesen Sie den Körper der POST-Nachricht mit den allgemeinen Details zur Benachrichtigung und den spezifischen Details zum Eventtyp in der Benachrichtigungen.

Für weitere Informationen zum Schema von POST-Anforderungen zum Ziehpunktsiehe das Zahlungsschema.

Richtlinie

Wenn eine Webhook-Benachrichtigung aufgrund von Fehlern wie Nichtverfügbarkeit des Endpunkts nicht auf die angegebene URL zugreifen kann, versucht Roblox, die Nachricht fünfmal an die angegebene URL mit einer festen Fenstergröße zu senden.Wenn die Benachrichtigung nach 5 Versuchen immer noch nicht geliefert werden kann, hört Roblox auf, die Benachrichtigung zu senden, und nimmt an, dass die URL nicht mehr gültig ist.In dieser Situation musst du deine Webhook-Konfiguration mit einer neuen URL aktualisieren, die erreichbar ist und Benachrichtigungen empfangen kann.Um Probleme zu beheben und zu bestätigen, dass deine Webhook-URL erfolgreich Benachrichtigungen empfangen kann, siehe Test-Webhooks.

Anforderungen an Dritte

Drittwerkzeuge haben in der Regel eigene Anforderungen an Webhooks, die Sie befolgen müssen, wenn Sie Ihre Webhook-URL einrichten.Du kannst diese Anforderungen finden, indem du nach dem Schlüsselwort "Webhook" auf der Unterstützungs- oder Dokumentationswebsite des Toolsuchst.Für die drei unterstützten Drittwerkzeuge siehe gefolgte Profile:

Testen von Webhooks

Du kannst testen, ob der Webhook, den du konfiguriert hast, erfolgreich Benachrichtigungen auf dem Creator-Dashboard empfangen kann:

Navigiere zur Webhooks Konfigurationsseite.
Wähle den Webhook aus, den du testen möchtest, aus der Liste der konfigurierten Webhooks.
Klicke auf das Bleistift-Symbol neben dem Ziel-Webhook.
Klicken Sie auf die Schaltfläche Testantwort .

Das System sendet dann eine Benachrichtigung im eingebenSampleNotification, die die Benutzer-ID des Benutzers enthält, der die Benachrichtigungenauslöst, wie das folgende Beispielsschema zeigt:

Beispielbenachrichtigungs Schema
Body: {
  "NotificationId": "string",
  "EventType": "SampleNotification",
  "EventTime": "2023-12-30T16:24:24.2118874Z", // Typ: ISO 8601 Zeitmarke
  "EventPayload": {
    "UserId": 1 // Typ: Lang
  }
}

Wenn du deinen Webhook mit einem Drittdienst integrierst, kannst du ihn mit der Drittdienst-URL testen, um zu bestätigen, dass der Dienst Benachrichtigungen von deinem Webhook erfolgreich empfangen kann.Wenn du beim Konfigurieren des Webhooks ein Geheimnis angeben, erzeugt es auch ein roblox-signature, das du verwenden kannst, um die roblox-signature Logik zu testen.

Überprüfen der Webhook-Sicherheit

Sobald du deinen Server konfiguriert hast, um Payloads zu empfangen, beginnt er, auf jede Payload zu hören, die an den Endpunkt gesendet wird.Wenn du ein Geheimnis während der Konfiguration deines Webhooks festlegst, sendet Roblox eine roblox-signature zusammen mit jeder Webhook-Benachrichtigung, um deine Daten-Sicherheit zu schützen.Auf diese Weise kannst du es verwenden, um zu überprüfen, dass die Benachrichtigung von Roblox stammt, und deinen Server nur auf Anfragen beschränken, die von Roblox stammen.Die Signatur befindet sich im Payload-Header für benutzerdefinierte Endpunkte und im Fußbereich für Drittserver.

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

Wenn du kein Geheimnis für deinen Webhook hast, enthält die Signatur, die du erhältst, nur den Zeitpunktswert, wenn die Benachrichtigung gesendet wird:

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

Um eine Signatur zu überprüfen:

Extrahiere den Zeitpunkt und die Signaturwerte.Alle Unterschriften für Webhooks mit Geheimnissen teilen das gleiche Format wie ein CSV-String mit diesen beiden Werten, gefolgt von den Präfixen:
- t : Der Zeitstempelwert, wenn die Benachrichtigung gesendet wird.
- v1 : Der Signaturwert, der mit dem geheimen Wert erzeugt wird, der von der Creator-Dashboard-Konfiguration bereitgestellt wird.Du kannst diese beiden Werte mit der split() -Funktion extrahieren, die den String basierend auf einem Trennzeichen, in diesem Fall der , -Zeiche, trennt.
Erstelle erneut die Basisstring von roblox-signature indem du konzipierst:
1. Der Zeitstempel als String.
2. Der Zeitzeichen ..
3. Der JSON-String des Körper.
Berechnen Sie einen Hash-basierten Nachrichtenauthentifizierungscode (HMAC) mit der SHA256-Hashfunktion, indem Sie den Geheimcode verwenden, den Sie während der Konfiguration als Schlüssel und die Basissequenz, die Sie durch Schritt 2 erzeugt haben, als Nachricht definieren.Konvertiere das Ergebnis in das Base64-Format, um die erwartete Signatur zu erhalten.
Vergleichen Sie den extrahierten Signaturwert mit der erwarteten Signatur. Wenn Sie die Signatur korrekt generiert haben, sollte der Wert gleich sein.
(Optional) Um Replay-Angriffe zu verhindern, ist es hilfreich, den extrahierten Zeitpunktswert mit dem aktuellen Zeitpunkt zu vergleichen und sicherzustellen, dass er innerhalb eines akzeptablen Zeitlimits liegt.Zum Beispiel ist ein 10-minütiges Fenster in der Regel eine gute vernünftige Zeit限制.

Zahlungs Schema

Wenn das Zielereignis deines Webhooks ausgelöst wird, sendet es eine Anfrage an deine Webhook-URL, einschließlich Informationen über das Ereignis im Payload.Alle Zahlungen von Anfragen teilen das gleiche Schema, das aus fixierten und variablen Feldern besteht.Dies gewährleistet, dass die in der Zahlung übermittelten Daten strukturiert und konsistent sind, was es der empfangenden Anwendung erleichtert, die Daten zu verarbeiten und zu verwenden.

Die 固定载荷协议字段 können helfen, die Konsistenz über alle Webhook-Anfragen aufrechtzuerhalten, mit den folgenden verfügbaren Feldern:

NotificationId , string : Ein eindeutiger Identifikator für jede gesendete Benachrichtigung. Wenn derselbe NotificationId zweimal empfangen wird, gilt er als Duplikat.
EventType , string : Ein String repräsentiert die Art von Ereignis, für die die Benachrichtigung ausgelöst wurde.
EventTime , timestamp : Ein ungefährer Zeitpunkt, der anzeigt, wann das Ereignis ausgelöst wurde.

Die variablen Payload- Schemafelder bieten Flexibilität für Webhooks, um verschiedene Arten von Ereignissen zu unterstützen, die umfassen:

EventPayload , object : Enthält Informationen, die sich auf das EventType beziehen, das den Webhook ausgelöst hat.Die Struktur des EventPayload Schemas variiert je nach Art des Ereignisses.

Das folgende Beispiel zeigt das Payload-Schema des Ereignisses Recht auf Löschanfrage :

Beispielschema für Anfrage auf Löschungsbefehl
Body:{

   "NotificationId": "string",

   "EventType": "RightToErasureRequest",

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

   "EventPayload": {

      "UserId": 1, // Typ: Lang

      "GameIds": [ // Typ: Eine Reihe von Langen

         1234, 2345

      ]

   }

}

Benachrichtigungen bearbeiten

Wenn du irgendeine personenbezogene Information (personenbezogene Daten ) deiner Benutzer speicherst, wie ihre Benutzer-IDs, musst du diese Information löschen, wenn ein Benutzer eine solche Anfrage einreicht, um die Vorgaben der DSGVO zum Recht auf Löschung zu erfüllen.Du kannst einen Bot erstellen, der Webhook-Benachrichtigungen bearbeitet und die Datenlöschung automatisiert, vorausgesetzt, du speicherst PII in einem Store.Siehe Automatisierung der Löschanfragenrechte für ein Beispiel, wie man einen Bot innerhalb von Guilded oder Discord erstellt, der die Open Cloud API für Datenspeicher verwendet, um PII-Daten als Automatisierungslösung zu löschen.Dieses Beispiel kann für die Verarbeitung anderer Benachrichtigungen angepasst werden, wie z. B. Abonnementereignisse.

Wenn du einen benutzerdefinierten Endpunkt als Webhook-Server anstelle eines Toolverwendest, kannst du die zu löschende Daten extrahieren aus dem Webhook-Payload und deine eigene Automatisierungslösung aufbauen.Das folgende Codebeispiel gibt eine Beispiellösung vor und fügt Prävention zu Wiedergabeangriffen hinzu, indem es überprüft wird, dass die Anfrage von Roblox stammt:

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')
})

Auf dieser Seite