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-Messaging-Tool oder Ihrem benutzerdefinierten Endpunkt zu erhalten, der HTTP-Anfragen empfangen kann. Dies hilft Ihnen, Ihren Workflow der Benachrichtigungsverwaltung zu automatisieren, um 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 herkömmlichen APIs, bei denen Sie eine Client-Anwendung einrichten müssen, um Anfragen an einen Server zu senden und 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 eine Echtzeit-Datenübertragung und -verarbeitung ermöglichen.

Sobald Sie einen Webhook eingerichtet haben und ein Zielereignis eintritt, sendet Roblox 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 in der Webhook-Nutzlast enthaltenen Daten Maßnahmen ergreifen kann. Dies könnte das Löschen von Daten zur Einhaltung von RTBF, das Versenden einer Bestätigung an den Benutzer oder das Auslösen eines anderen Ereignisses umfassen.

Unterstützte Trigger

Roblox unterstützt derzeit die folgenden Ereignis-Trigger.

Abonnierung

• Abonnierung Wiederabonnieren - Wenn ein Benutzer ein Abonnement wiederabonnieren möchte, wird eine Nachricht gesendet, die das Abonnement und den Abonnenten enthält.
• Abonnierung Erneuert - Wenn ein Benutzer ein Abonnement erneuert, wird eine Nachricht gesendet, die das Abonnement und den Abonnenten enthält.
• Abonnierung 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.
• Abonnierung Gekauft - Wenn ein Benutzer ein Abonnement kauft, wird eine Nachricht gesendet, die das Abonnement und den Abonnenten enthält.
• Abonnierung Abgebrochen - Wenn ein Benutzer ein Abonnement abbricht, 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.

Compliance

• Recht auf Löschung / Löschanfrage - Wenn ein Benutzer sein Recht ausübt, dass seine personenbezogenen Daten gemäß geltenden globalen Datenschutz- und Privatsphäre-Vorschriften dauerhaft gelöscht werden. 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 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. Bei gruppeneigenen Spielen können nur Gruppeninhaber Webhook-Benachrichtigungen konfigurieren und empfangen.

Um einen Webhook einzurichten:

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

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

   Die Webhook-URL stammt von Ihrem Anbieter. Zum Beispiel könnte eine Slack-URL so aussehen:

   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 für die Ereignisse 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 Testanfrage empfangen kann.

7. Klicken Sie auf Änderungen speichern.

Webhook-URLs einrichten

Sie können einen benutzerdefinierten HTTP-Dienstopunkt 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 auf die Anfrage innerhalb von 5 Sekunden mit einer 2XX-Antwort reagieren.
• Er kann HTTPS-Anfragen verarbeiten.

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

• Die erforderlichen Details zu der 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 der Benachrichtigung zu lesen.

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

Wiederholungsrichtlinie bei Zustellfehlern

Wenn eine Webhook-Benachrichtigung Ihre angegebene URL aufgrund von Fehlern wie Nichtverfügbarkeit des Endpunkts nicht erreicht, versucht Roblox, die Nachricht 5 Mal unter Verwendung 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, 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 Benachrichtigungen erfolgreich empfangen kann, siehe Webhooks testen.

Anforderungen an Drittanbieter

Drittanbieter-Tools haben in der Regel ihre eigenen Anforderungen an Webhooks, die Sie bei der Einrichtung Ihrer Webhook-URL befolgen müssen. Sie finden diese Anforderungen, 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 im Creator Dashboard empfangen kann:

1. Navigieren Sie zur Konfigurationsseite für Webhooks.
2. Wählen Sie den Webhook aus, den Sie aus der Liste der konfigurierten Webhooks testen möchten.
3. Klicken Sie auf das Bleistift-Symbol neben dem Ziel-Webservices.
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 mithilfe 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 Logik der roblox-signature zu testen.

Webhook-Sicherheit überprüfen

Nachdem Sie Ihren Server so konfiguriert haben, dass er Nutzlasten empfängt, beginnt er, auf alle an den Endpunkt gesendeten Nutzlasten zu hören. 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 Nutzlast-Header für benutzerdefinierte Endpunkte und im Fußbereich 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, zu dem die Benachrichtigung gesendet wurde:

t=<timestamp>

Um eine Signatur zu verifizieren:

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

   • t: Der Zeitstempel, zu dem die Benachrichtigung gesendet wurde.
   • v1: Der Signaturwert, der mit dem beim Creator Dashboard konfigurierten Geheimnis generiert wurde.

2. Rekonstruieren Sie die Basiszeichenfolge der roblox-signature, indem Sie folgendermaßen verketten:

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

3. Berechnen Sie einen Hash-basierten Nachrichten-Authentifizierungscode (HMAC) mit der SHA256-Hashfunktion und verwenden Sie das während der Konfiguration definierte Geheimnis als Schlüssel und die Basiszeichenfolge, die Sie in Schritt 2 erstellt 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 identisch 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ösartige Aktionen durchzuführen, ist es hilfreich, den extrahierten Zeitstempelwert mit dem aktuellen Zeitstempel zu vergleichen und sicherzustellen, dass dieser innerhalb eines angemessenen Zeitlimits liegt. Zum Beispiel ist ein Zeitrahmen von 10 Minuten in der Regel ein gutes angemessenes Zeitlimit.

Nutzlastschema

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

Die festen Nutzlast-Schemas helfen, die Konsistenz über alle Webhook-Anfragen hinweg aufrechtzuerhalten, mit den folgenden verfügbaren Feldern:

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

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

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

Das folgende Beispiel zeigt das Nutzlastschema des Rechts auf Löschanfrage-Ereignisses:

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

Benachrichtigungen bearbeiten

Wenn Sie personenbezogene Daten (PII) Ihrer Nutzer 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 bearbeiten und das Löschen von Daten zu automatisieren, vorausgesetzt, Sie speichern PII in einem Datenspeicher. Siehe Automatisierung von Löschanfragen 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 bearbeiten.

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

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 empfangen');

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

   // Validieren Sie die Signatur
   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 zum Bearbeiten der Nutzlast
   const payloadBody = req.body;
   const eventType = payloadBody['EventType'];

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

      console.log(`Nutzlastdaten: 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: 'Die Nachricht wurde erfolgreich verarbeitet' });
});

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