Webhook-Benachrichtigungen

Anstatt alle Ereignisse in Ihrem Spiel und Anfragen von Nutzern manuell zu überwachen, können Sie Webhooks einrichten, um Echtzeitbenachrichtigungen in einem Drittanbieter-Nachrichtentool oder an Ihren benutzerdefinierten Endpunkt, der HTTP-Anfragen empfangen kann, zu erhalten. Dies hilft Ihnen dabei, Ihren Workflow zur Verwaltung von Benachrichtigungen zu automatisieren und den manuellen Aufwand bei der Handhabung von Benachrichtigungen zu reduzieren.

Webhook-Workflow

Webhooks senden Echtzeitbenachrichtigungen oder Daten zwischen zwei verschiedenen Anwendungen oder Diensten, etwa Roblox und einem Drittanbieter-Nachrichtentool. Im Gegensatz zu herkömmlichen APIs, die es erforderlich machen, eine Clientanwendung einzurichten, um Anfragen an einen Server zu senden und Daten zu empfangen, senden Webhooks Daten an Ihren Client-Endpunkt, sobald ein Ereignis eintritt. Sie sind nützlich, um Workflows zwischen Roblox und Drittanbieteranwendungen, die Sie zur Zusammenarbeit mit Ihrem Team verwenden, zu automatisieren, da sie ein Echtzeit-Datenaustausch und -verarbeitung ermöglichen.

Sobald Sie einen Webhook eingerichtet haben, sendet Roblox, wann immer ein Zielereignis eintritt, eine Anfrage an die von Ihnen angegebene Webhook-URL. Die Webhook-URL leitet dann die Anfrage an Ihre empfangende Anwendung oder Ihren benutzerdefinierten Endpunkt weiter, der auf der Grundlage der im Webhook-Payload enthaltenen Daten Maßnahmen ergreifen kann. Dies könnte das Löschen von Daten zur Einhaltung der DSGVO, das Senden einer Bestätigung an den Benutzer oder das Auslösen eines weiteren 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 Grund für die Stornierung enthält.

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

Compliance

• Recht auf Löschung Anfrage - Wenn ein Benutzer eine Anfrage zur Datenlöschung gemäß der Allgemeinen Datenschutzverordnung (DSGVO) einreicht.

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 anhand der eindeutigen Handelsbestell-ID deduplizieren.

Webhooks im Creator Dashboard konfigurieren

Um Benachrichtigungen über Webhooks zu erhalten, müssen Sie einen Webhook konfigurieren, der auf bestimmte Ereignisse zum Auslösen von Benachrichtigungen abonniert ist. Für gruppenbesessene Spiele können nur Gruppenbesitzer Webhook-Benachrichtigungen konfigurieren und empfangen.

Um einen Webhook einzurichten:

1. Wählen Sie Ihr Erlebnis im Creator Hub aus.

2. Wählen Sie unter Konfigurieren die Option 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 prüfen, ob Ihr Dienst eine Beispielanfrage erhalten kann.

7. Klicken Sie auf Änderungen speichern.

Webhook-URLs einrichten

Sie können einen benutzerdefinierten HTTP-Service-Endpunkt 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 behandeln.
• Er kann auf die Anfrage innerhalb von 5 Sekunden mit einer 2XX-Antwort antworten.
• 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 in Bezug auf den Ereignistyp in der Benachrichtigung zu lesen.

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

Richtlinie für Zustellfehlerwiederholungen

Wenn eine Webhook-Benachrichtigung aufgrund von Fehlern wie Nichtverfügbarkeit des Endpunkts nicht Ihre angegebene URL erreicht, versucht Roblox, die Nachricht fünfmal an die konfigurierte URL mit einer festen Fenstergröße zu senden. Wenn die Benachrichtigung nach 5 Versuchen immer noch nicht zugestellt werden kann, hört Roblox auf, zu versuchen, 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 Webhook testen.

Anforderungen von Drittanbietern

Drittanbieter-Tools haben in der Regel ihre eigenen Anforderungen für Webhooks, die Sie befolgen müssen, wenn Sie Ihre Webhook-URL einrichten. 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 die folgenden:

• Discord Hilfe-Center
• Slack API-Referenz

Webhooks testen

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

1. Navigieren Sie zur Seite zur Konfiguration der Webhooks.
2. Wählen Sie den Webhook aus, den Sie testen möchten, aus der Liste der konfigurierten Webhooks.
3. Klicken Sie auf das Bleistift-Symbol neben dem Ziel-Webhooks.
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:

SampleNotification-Schema
{
  "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 unter Verwendung der Drittanbieter-URL testen, um zu bestätigen, dass der Dienst Benachrichtigungen erfolgreich 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 roblox-signature-Logik zu testen.

Webhook-Sicherheit überprüfen

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

Signaturformat mit Geheimnis für benutzerdefinierte Endpunkte
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:

Signaturformat ohne Geheimnis für benutzerdefinierte Endpunkte
t=<timestamp>

Um eine Signatur zu überprüfen:

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

   • 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. Rekonstruieren Sie den Basisstring der roblox-signature, indem Sie Folgendes zusammenfügen:

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

3. Berechnen Sie einen Hash-basierten Nachrichtenauthentifizierungscode (HMAC) mit der SHA256-Hashfunktion, wobei Sie das Geheimnis, das Sie während der Konfiguration definiert haben, als Schlüssel verwenden und den Basisstring, den Sie durch 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 Replay-Angriffe zu verhindern, eine Art von Cyberangriff, bei dem Angreifer Daten abfangen und erneut senden, um unbefugten Zugriff zu erhalten oder schädliche Aktionen durchzuführen, ist es hilfreich, den extrahierten Zeitstempelwert mit dem aktuellen Zeitstempel zu vergleichen und sicherzustellen, dass er innerhalb eines angemessenen Zeitrahmens liegt. Zum Beispiel ist ein Zeitfenster von 10 Minuten normalerweise eine gute angemessene Zeitgrenze.

Payload-Schema

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

Die festen Payload-Schematafelder können dazu beitragen, 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 dasselbe NotificationId zweimal empfangen wird, wird dies 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-Schematafelder 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-Ereignisses:

Beispiel-Schema für eine Recht auf Löschung Anfrage
{
   "NotificationId": "string",
   "EventType": "RightToErasureRequest",
   "EventTime": "2023-12-30T16:24:24.2118874Z",
   "EventPayload": {
      "UserId": 1,
      "GameIds": [
         1234, 2345
      ]
   }
}

Benachrichtigungen verarbeiten

Wenn Sie Informationen über persönlich identifizierbare Informationen (PII) Ihrer Nutzer speichern, wie z. B. ihre Benutzer-IDs, müssen Sie diese Informationen löschen, wenn ein Benutzer eine solche Anfrage einreicht, um den Anforderungen der DSGVO Recht auf Löschung zu entsprechen. Sie können einen Bot erstellen, der Webhook-Benachrichtigungen verarbeitet und dabei hilft, die Datenlöschung zu automatisieren, vorausgesetzt, Sie speichern PII in einem Datenspeicher. Siehe Automatisierung der Löschung von Recht auf Löschung Anfragen 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 Abonnementereignisse zu verarbeiten.

Wenn Sie anstelle eines Drittanbieter-Tools einen benutzerdefinierten Endpunkt als Ihren Webhook-Server verwenden, können Sie die zu löschenden Daten aus dem Webhook-Payload extrahieren und Ihre eigene Automatisierungslösung erstellen. Der folgende Codeausschnitt ist ein Beispiel für einen Server, der verhindert, dass Replay-Angriffe stattfinden, indem er den Zeitstempel überprüft und sicherstellt, dass die Anfrage von Roblox stammt:

PII aus Payload extrahieren
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');

   // Zeitstempel und Signatur aus Header extrahieren
   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);

   // Sicherstellen, dass die Anfrage innerhalb eines 300-Sekunden-Fensters eingegangen ist, um Replay-Angriffe 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 der 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-Daten: Benutzer-ID=${userId} und Spiel-IDs=${gameIds}`);
      // Wenn Sie PII in Datenspeichern speichern, verwenden Sie die Benutzer-ID und die Spiel-IDs, um die Informationen aus den Datenspeichern zu löschen.
   }

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

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