Webhook-Benachrichtigungen

Anstatt alle Ereignisse in Ihrem Spiel und Anfragen von Benutzern manuell zu überwachen, können Sie Webhooks einrichten, um Echtzeitbenachrichtigungen über ein Drittanbieter-Messaging-Tool oder Ihren benutzerdefinierten Endpunkt zu erhalten, der HTTP-Anfragen empfangen kann. Dies hilft Ihnen, Ihren Workflow zur Verwaltung von Benachrichtigungen zu automatisieren und den manuellen Aufwand bei der Bearbeitung von Benachrichtigungen zu reduzieren.

Webhook-Workflow

Webhooks senden Echtzeitbenachrichtigungen oder Daten zwischen zwei verschiedenen Anwendungen oder Diensten, wie Roblox und einem Drittanbieter-Messaging-Tool. Im Gegensatz zu traditionellen APIs, die erfordern, dass Sie eine Client-Anwendung einrichten, um Anfragen an einen Server zu senden, um Daten zu erhalten, senden Webhooks Daten an Ihren Client-Endpunkt, sobald ein Ereignis eintritt. Sie sind nützlich, um Workflows zwischen Roblox und Drittanbieter-Anwendungen zu automatisieren, die Sie zur Zusammenarbeit mit Ihrem Team verwenden, da sie den Echtzeit-Datenaustausch und die Verarbeitung ermöglichen.

Sobald Sie einen Webhook eingerichtet haben, sendet Roblox jedes Mal, wenn ein Zielereignis eintritt, eine Anfrage an die von Ihnen angegebene Webhook-URL. Die Webhook-URL leitet die Anfrage dann an Ihre empfangende Anwendung oder Ihren benutzerdefinierten Endpunkt weiter, der basierend auf den im Webhook-Payload enthaltenen Daten Maßnahmen ergreifen kann. Dies könnte das Löschen von Daten zur Einhaltung von RTBF, das Senden einer Bestätigung an den Benutzer oder das Auslösen eines anderen Ereignisses umfassen.

Unterstützte Trigger

Roblox unterstützt derzeit die folgenden Ereignistrigger.

Abonnement

• Abonnement erneut abonniert - Wenn ein Benutzer ein Abonnement erneut abonniert, wird eine Nachricht gesendet, die das Abonnement und den Abonnenten enthält.
• Abonnement erneuert - Wenn ein Benutzer ein Abonnement erneuert, wird eine Nachricht gesendet, die das Abonnement und den Abonnenten enthält.
• Abonnement erstattet - Wenn ein Benutzer eine Rückerstattung für sein Abonnement erhält, wird eine Nachricht gesendet, die das Abonnement und den Abonnenten enthält.
• Abonnement gekauft - Wenn ein Benutzer ein Abonnement kauft, wird eine Nachricht gesendet, die das Abonnement und den Abonnenten enthält.
• Abonnement storniert - Wenn ein Benutzer ein Abonnement storniert, wird eine Nachricht gesendet, die das Abonnement und den Abonnenten sowie den angegebenen Grund für die Stornierung enthält.

Für weitere Informationen zu Abonnementereignissen und deren Feldern siehe das Abonnement Referenzdokument.

Einhaltung

• Recht auf Löschung / Löschanfrage - Wenn ein Benutzer sein Recht ausübt, seine personenbezogenen Daten gemäß den geltenden globalen Datenschutz- und Privatsphäre-Vorschriften dauerhaft löschen zu lassen. Weitere Informationen finden Sie in RTBF und Creators.

Handel

• Handelsproduktbestellung erstattet - Wenn ein Benutzer eine Rückerstattung für seine Handelsproduktbestellung erhalten hat oder die Bestellung storniert wurde.
• Handelsproduktbestellung bezahlt - Wenn ein Benutzer für seine Handelsproduktbestellung bezahlt hat. Bitte beachten Sie, dass doppelte Webhook-Ereignisse möglich sind, daher sollten Sie Ereignisse mit der eindeutigen Handelsbestell-ID deduplizieren.

Webhooks im Creator Dashboard konfigurieren

Um Benachrichtigungen über Webhooks zu erhalten, müssen Sie einen Webhook konfigurieren, der sich für bestimmte Ereignisse anmeldet, um Benachrichtigungen auszulösen. Für gruppeneigene Spiele können nur Gruppenbesitzer Webhook-Benachrichtigungen konfigurieren und empfangen.

Um einen Webhook einzurichten:

1. Wählen Sie Ihre Erfahrung im Creator Hub aus.

2. Unter Konfigurieren wählen Sie Webhooks und klicken Sie auf Webhook hinzufügen.

   Die Webhook-URL stammt von Ihrem Anbieter. Eine Slack-URL sieht beispielsweise wahrscheinlich so aus:

   https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX

3. Geben Sie Ihre Webhook-URL und einen Namen ein.

4. OPTIONAL

   Fügen Sie ein Geheimnis hinzu, das hilft sicherzustellen, dass die Benachrichtigungen, die Sie erhalten, von Roblox stammen. Weitere Informationen finden Sie unter Webhook-Sicherheit überprüfen.

5. Wählen Sie eine oder mehrere Optionen aus der Liste der unterstützten Trigger von Ereignissen aus, für die Sie Benachrichtigungen erhalten möchten.

6. OPTIONAL

   Verwenden Sie die Schaltfläche Testantwort, um zu überprüfen, ob Ihr Dienst eine Beispielanfrage empfangen kann.

7. Klicken Sie auf Änderungen speichern.

Webhook-URLs einrichten

Sie können einen benutzerdefinierten HTTP-Dienstendpunkt als Ihre Webhook-URL einrichten, vorausgesetzt, er erfüllt die folgenden Anforderungen:

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

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

• Die erforderlichen Details zur Benachrichtigung aus dem Body der POST-Nachricht zu extrahieren.
• Den Body der POST-Nachricht mit den allgemeinen Details zur Benachrichtigung und spezifischen Details zum Ereignistyp in der Benachrichtigung zu lesen.

Für weitere Informationen zum Schema der zu verarbeitenden POST-Anfragen siehe das Payload-Schema.

Richtlinie für den Wiederholungsversuch bei Zustellfehlern

Wenn eine Webhook-Benachrichtigung Ihre angegebene URL aufgrund von Fehlern wie der Nichtverfügbarkeit des Endpunkts nicht erreicht, versucht Roblox, die Nachricht 5 Mal mit einer festen Fenstergröße an die konfigurierte URL zu senden. Wenn die Benachrichtigung nach 5 Versuchen immer noch nicht zugestellt werden kann, hört Roblox auf, die Benachrichtigung zu senden, und geht davon aus, dass die URL nicht mehr gültig ist. In diesem Fall müssen Sie Ihre Webhook-Konfiguration mit einer neuen URL aktualisieren, die erreichbar ist und Benachrichtigungen empfangen kann. Um zu überprüfen und zu bestätigen, dass Ihre Webhook-URL erfolgreich Benachrichtigungen empfangen kann, siehe Webhooks testen.

Anforderungen von Drittanbietern

Drittanbieter-Tools haben in der Regel ihre eigenen Anforderungen für Webhooks, die Sie bei der Einrichtung Ihrer Webhook-URL befolgen müssen. Sie können diese Anforderungen finden, indem Sie auf der Support- oder Dokumentationsseite des Zieltools nach dem Schlüsselwort "Webhook" suchen. Für die unterstützten Drittanbieter-Tools siehe Folgendes:

• Discord-Hilfecenter
• Slack-API-Referenz

Webhooks testen

Sie können testen, ob der konfigurierte Webhook erfolgreich Benachrichtigungen auf dem Creator Dashboard empfangen kann:

1. Navigieren Sie zur Konfigurationsseite Webhooks.
2. Wählen Sie den Webhook aus, den Sie aus der Liste der konfigurierten Webhooks testen möchten.
3. Klicken Sie auf das Stiftsymbol neben dem Ziel-Webhook.
4. Klicken Sie auf die Schaltfläche Testantwort.

Das System sendet dann ein SampleNotification-Ereignis, das die Benutzer-ID des Benutzers enthält, der die Benachrichtigung ausgelöst hat, wie hier gezeigt:

{
  "NotificationId": "string",
  "EventType": "SampleNotification",
  "EventTime": "2023-12-30T16:24:24.2118874Z",
  "EventPayload": {
    "UserId": 1
  }
}

Wenn Sie Ihren Webhook mit einem Drittanbieterdienst integrieren, können Sie ihn mit der Drittanbieter-URL testen, um zu bestätigen, dass der Dienst erfolgreich Benachrichtigungen von Ihrem Webhook empfangen kann. Wenn Sie ein Geheimnis bei der Konfiguration des Webhooks angeben, wird auch eine roblox-signature generiert, die Sie verwenden können, um die Logik der roblox-signature zu testen.

Webhook-Sicherheit überprüfen

Nachdem Sie Ihren Server konfiguriert haben, um Payloads zu empfangen, beginnt er, auf alle Payloads zu hören, die an den Endpunkt gesendet werden. Wenn Sie ein Geheimnis bei der Konfiguration Ihres Webhooks festgelegt haben, sendet Roblox in jeder Webhook-Benachrichtigung eine roblox-signature, um sicherzustellen, dass die Anfrage tatsächlich von Roblox stammt. Die Signatur befindet sich im Payload-Header für benutzerdefinierte Endpunkte und im Footer für Drittanbieter-Server.

t=<timestamp>,v1=<signature>

Wenn Sie kein Geheimnis für Ihren Webhook festgelegt haben, enthält die Signatur nur den Zeitstempel, wann die Benachrichtigung gesendet wurde:

t=<timestamp>

Um eine Signatur zu überprüfen:

1. Extrahieren Sie die Werte für Zeitstempel und Signatur. Alle Signaturen für Webhooks mit Geheimnissen haben dasselbe Format als CSV-Zeichenfolge mit diesen beiden Werten, die von den Präfixen gefolgt werden:

   • t: Der Zeitstempel, wann die Benachrichtigung gesendet wurde.
   • v1: Der Signaturwert, der mit dem Geheimnis generiert wurde, das in der Konfiguration des Creator Dashboards angegeben wurde.

2. Erstellen Sie die Basiszeichenfolge der roblox-signature neu, indem Sie Folgendes verketten:

   1. Den Zeitstempel als Zeichenfolge.
   2. Das Punktzeichen ..
   3. Die JSON-Zeichenfolge des Anfragekörpers.

3. Berechnen Sie einen Hash-basierten Nachrichtenauthentifizierungscode (HMAC) mit der SHA256-Hashfunktion, wobei Sie das Geheimnis verwenden, das Sie während der Konfiguration als Schlüssel definiert haben, und die Basiszeichenfolge, die Sie in Schritt 2 generiert haben, als Nachricht. Konvertieren Sie das Ergebnis in das Base64-Format, um die erwartete Signatur zu erhalten.

4. Vergleichen Sie den extrahierten Signaturwert mit der erwarteten Signatur. Wenn Sie die Signatur korrekt generiert haben, sollte der Wert gleich sein.

5. OPTIONAL

   Um Wiederholungsangriffe zu verhindern, eine Art von Cyberangriff, bei dem Angreifer Daten abfangen und erneut senden, um unbefugten Zugriff zu erlangen oder böswillige Aktionen durchzuführen, ist es hilfreich, den extrahierten Zeitstempelwert mit dem aktuellen Zeitstempel zu vergleichen und sicherzustellen, dass er innerhalb eines angemessenen Zeitlimits liegt. Zum Beispiel ist ein Zeitfenster von 10 Minuten normalerweise ein gutes angemessenes Zeitlimit.

Payload-Schema

Wenn das Zielereignis Ihres Webhooks ausgelöst wird, sendet es eine Anfrage an Ihre Webhook-URL, die Informationen über das Ereignis im Payload enthält. Alle Payloads von Anfragen teilen dasselbe Schema, das aus festen und variablen Feldern besteht. Dies stellt sicher, dass die im Payload übertragenen Daten strukturiert und konsistent sind, was es der empfangenden Anwendung erleichtert, die Daten zu verarbeiten und zu verwenden.

Die festen Payload-Schema-Felder können helfen, die Konsistenz über alle Webhook-Anfragen hinweg aufrechtzuerhalten, wobei die folgenden Felder verfügbar sind:

1. NotificationId (string): Eine eindeutige Kennung für jede gesendete Benachrichtigung. Wenn dieselbe NotificationId zweimal empfangen wird, wird sie als Duplikat betrachtet.
2. EventType (string): Gibt den Typ des Ereignisses an, für das die Benachrichtigung ausgelöst wurde.
3. EventTime (string): Der Zeitstempel, wann das Ereignis ausgelöst wurde.

Die variablen Payload-Schema-Felder bieten Flexibilität für Webhooks, um verschiedene Arten von Ereignissen zu berücksichtigen, die Folgendes umfassen:

1. EventPayload (object): Enthält Informationen, die spezifisch für den EventType sind, der den Webhook ausgelöst hat. Die Struktur des EventPayload-Schemas variiert je nach Art des Ereignisses.

Das folgende Beispiel zeigt das Payload-Schema des Rechts auf Löschung-Anfrage-Ereignisses:

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

Benachrichtigungen verarbeiten

Wenn Sie personenbezogene Daten (PII) Ihrer Benutzer speichern, wie z.B. deren Benutzer-IDs, sollten Sie die Anfrage im Hinblick auf Ihre gesetzlichen Verpflichtungen bewerten. Weitere Informationen finden Sie in RTBF und Creators. Sie können einen Bot erstellen, um Webhook-Benachrichtigungen zu verarbeiten und das Löschen von Daten zu automatisieren, vorausgesetzt, Sie speichern PII in einem Datenspeicher. Siehe Automatisierung von Löschanfragen für das Recht auf Löschung für ein Beispiel, wie man einen Bot innerhalb von Discord erstellt, der die Open Cloud API für Datenspeicher verwendet, um PII-Daten als Automatisierungslösung zu löschen. Dieses Beispiel kann angepasst werden, um andere Benachrichtigungen, wie z.B. Abonnementereignisse, zu verarbeiten.

Wenn Sie einen benutzerdefinierten Endpunkt als Ihren Webhook-Server anstelle eines Drittanbieter-Tools verwenden, können Sie die Daten, die gelöscht werden sollen, aus dem Webhook-Payload extrahieren und Ihre eigene Automatisierungslösung erstellen. Das folgende Codebeispiel ist ein Beispiel für einen Server, der gegen Wiederholungsangriffe geschützt ist, indem er den Zeitstempel überprüft und sicherstellt, dass die Anfrage von Roblox stammt:

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

const secret = '<your_secret>' // Dies kann als Umgebungsvariable festgelegt werden

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

app.all('/*', function (req, res) {
   console.log('Neue Anfrage erhalten');

   // Extrahieren Sie den Zeitstempel und die Signatur aus dem 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);

   // Stellen Sie sicher, dass die Anfrage innerhalb eines 300-Sekunden-Fensters kam, um Wiederholungsangriffe zu verhindern
   const requestTimestampMs = timestamp * 1000;
   const windowTimeMs = 300 * 1000;
   const oldestTimestampAllowed = Date.now() - windowTimeMs;

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

   // Signatur validieren
   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('Unbefugte Anfrage');
   }

   // Ihre Logik zur Verarbeitung des Payloads
   const payloadBody = req.body;
   const eventType = payloadBody['EventType'];

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

      console.log(`Payload-Daten: UserId=${userId} und GameIds=${gameIds}`);
      // Wenn Sie PII in Datenspeichern speichern, verwenden Sie die UserId und GameIds, um die Informationen aus den Datenspeichern zu löschen.
   }

   return res.json({ message: 'Nachricht erfolgreich verarbeitet' });
});

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