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 angegebene Webhook-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 Ereignisauslöser.

Abo

Abonnement wieder abonniert - Wenn ein Benutzer ein Abonnement wieder abonniert, wird eine Nachricht mit dem Abonnement und dem Abonnenten gesendet.
Abonnement verlängert - Wenn ein Benutzer ein Abonnement erneuert, 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 gekauft - Wenn ein Benutzer ein Abonnement kauft, wird eine Nachricht mit dem Abonnement und dem Abonnenten gesendet.
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.

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

Konformität

Recht auf Löschanfrage - Wenn ein Benutzer eine Datenlöschanfrage gemäß der Allgemeinen Datenschutzverordnung (GDPR) einreicht.

Kommerce

Handelsprodukt-Rückerstattung - Wenn ein Benutzer eine Rückerstattung für seine Handelsproduktbestellung erhalten hat oder die Bestellung abgebrochen wurde.
Einkaufsproduktbestellung bezahlt - Wenn ein Benutzer für seine Einkaufsproduktbestellung bezahlt hat.Bitte beachten Sie, dass doppelte Webhook-Ereignisse möglich sind, sodass Sie Ereignisse duplizieren sollten, indem Sie die eindeutige Handelsbestellungs-ID verwenden.

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 (ADGPR) 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 - Geben Sie die URL an, über die Sie Benachrichtigungen empfangen möchten.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 im Zusammenhang mit dem Eventtyp in der Benachrichtigung.

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

Lieferfehlern-Wiederholungsrichtlinie

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 Zieltools suchst.Für die drei unterstützten Drittwerkzeuge siehe Folgendes:

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 ein Ereignis SampleNotification, das die Benutzer-ID des Benutzers enthält, der die Benachrichtigung ausgelöst hat, wie hier gezeigt:

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

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

Nachdem du deinen Server konfiguriert hast, um Lasten zu empfangen, beginnt er, auf jede Last zu hören, die an den Endpunkt gesendet wird.Wenn du ein Geheimnis festlegst, wenn du deinen Webhook konfigurierst, sendet Roblox eine roblox-signature in jeder Webhook-Benachrichtigung, um sicherzustellen, dass die Anfrage tatsächlich von Roblox kam.Die Signatur befindet sich im Payload-Header für benutzerdefinierte Endpunkte und im Fußbereich für Drittserver.

Signature format with a secret for custom endpoints
t=<timestamp>,v1=<signature>

Wenn du kein Geheimnis für deinen Webhook festgelegt hast, enthält die Signatur nur den Zeitstempel, in dem die Benachrichtigung gesendet wurde:

Signature format without a secret for custom endpoints
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 Zeitstempel, in dem die Benachrichtigung gesendet wurde.
- v1 : Der Signaturwert, der mit dem geheimen Wert erzeugt wird, der von der Creator-Dashboard-Konfiguration bereitgestellt wird.
Erstelle erneut die Basisstring von roblox-signature indem du konzipierst:
1. Der Zeitstempel als String.
2. Der Zeitzeichen ..
3. Der JSON-String des Anforderungskörpers.
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 (Schnur): Eine eindeutige Kennung für jede gesendete Benachrichtigung. Wenn das gleiche NotificationId zweimal empfangen wird, gilt es als Duplikat.
EventType (Schnur): Zeigt den Typ des Ereignisses an, für das die Benachrichtigung ausgelöst wurde.
EventTime (Schnur): Der Zeitpunkt, an dem 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 (Objekt): Enthält Informationen, die spezifisch für die EventType sind, die den Webhook ausgelöst haben.Die Struktur des EventPayload Schemas variiert je nach Art des Ereignisses.

Das folgende Beispiel zeigt das Payload-Schema der Recht auf Löschung-Anfrage -Veranstaltung:

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

Benachrichtigungen bearbeiten

Wenn du irgendeine personenbezogene Information (PII) 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 Datenstore.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 Drittwerkzeugs verwendest, kannst du die zu löschende Daten extrahieren aus dem Webhook-Payload und deine eigene Automatisierungslösung aufbauen.Das folgende Codebeispiel ist ein Beispiel für einen Server, der eine Prävention gegen Wiedergabeangriffe durch die Überprüfung des Zeitstempels und dass die Anfrage von Roblox stammt:

Extracting PII from Payload
const crypto = require('crypto');
const express = require('express');

const secret = '<your_secret>' // This can be set as an environment variable

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

app.all('/*', function (req, res) {
   console.log('New request recieved');

   // Extract the timestamp and signature from 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);

   // Ensure the request came within a 300 second window to prevent replay attacks
   const requestTimestampMs = timestamp * 1000;
   const windowTimeMs = 300 * 1000;
   const oldestTimestampAllowed = Date.now() - windowTimeMs;

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

   // Validate signature
   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('Unauthorized Request');
   }

   // 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'];

      console.log(`Payload data: UserId=${userId} and GameIds=${gameIds}`);
      // If you store PII in data stores, use the UserId and GameIds to delete the information from data stores.
   }

   return res.json({ message: 'Processed the message successfully' });
});

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

Auf dieser Seite