Powiadomienia Webhook

Zamiast ręcznie monitorować wszystkie wydarzenia w swoim doświadczeniu i wnioski od użytkowników, możesz skonfigurować webhooki, aby otrzymywać powiadomienia w czasie rzeczywistym na narzędziu do wysyłania wiadomości od strony trzeciej lub na niestandardowym punktie końcowym, który może otrzymywać żądania HTTP.Pomaga to zautomatyzować proces zarządzania powiadomieniami, aby zmniejszyć ręczne przetwarzanie powiadomień o wysiłku.

Obecnie Roblox w pełni wspiera powiadomienia webhook dla Discord, Guilded i Slack.Korzystanie z webhooków z innymi narzędziami stron trzecich niesie ryzyko nie otrzymywania wszystkich powiadomień.

Przepływ pracy Webhook

Webhooks wysyłają powiadomienia lub dane w czasie rzeczywistym między dwiema różnymi aplikacjami lub usługami, takimi jak Roblox i narzędziem do wysyłania wiadomości od strony trzeciej.W przeciwieństwie do tradycyjnych interfejsów programistycznych, które wymagają ustawienia aplikacji klienta, aby wysyłać żądania do serwera, aby otrzymać dane, webhooks wysyłają dane do punktu końcowego klienta, gdy tylko wystąpi zdarzenie.Są przydatne do automatyzacji przepływów pracy między Robloxem a aplikacjami stron trzecich, których używasz do współpracy z Twoim zespołem, ponieważ umożliwiają współdzielenie i przetwarzanie danych w czasie rzeczywistym.

Gdy skonfigurujesz webhook, za każdym razem, gdy wystąpi celowe wydarzenie, Roblox wysyła żądanie do URL webhooka, który podasz.Adres URL webhook przekieruje wówczas żądanie do odbiorczej aplikacji lub niestandardowego punktu końcowego, który może podjąć działania w oparciu o dane zawarte w zapytaniu webhook.Może to obejmować usuwanie danych dla RODO, wysyłanie potwierdzenia użytkownikowi lub uruchomienie innego wydarzenia.

Wspierane uruchomienia

Roblox obecnie wspiera następujące uruchomienia wydarzeń.

Subskrypcja

Subskrypcja odnowiona - Kiedy użytkownik odnowi subskrypcję, wysyłana jest wiadomość zawierająca subskrypcję i subskrybenta.
Subskrypcja odnowiona - Kiedy użytkownik odnawia subskrypcję, wysyłana jest wiadomość zawierająca subskrypcję i subskrybenta.
Subskrypcja zwrócona - Kiedy użytkownik otrzymuje zwrot za subskrypcję, wysyłana jest wiadomość zawierająca subskrypcję i subskrybenta.
Subskrypcja zakupiona - Kiedy użytkownik kupuje subskrypcję, wysyłana jest wiadomość zawierająca subskrypcję i subskrybenta.
Subskrypcja anulowana - Kiedy użytkownik anuluje subskrypcję subskrypcję, wysyłana jest wiadomość zawierająca subskrypcję i subskrybenta, a także powód anulowania.

Aby uzyskać więcej informacji na temat wydarzeń subskrypcyjnych i ich pól, zobacz odniesienie Subskrypcja.

Zgodność

Prawo do wniosku o usunięcie danych - Kiedy użytkownik składa wniosek o usunięcie danych w ramach Ogólnego rozporządzenia o ochronie danych (RODO).

Komercja

Zamówienie produktu handlowego zwrócone - Kiedy użytkownik otrzymał zwrot za zamówienie produktu handlowego lub zamówienie zostało anulowane.
Zamówienie produktu handlowego opłacone - Kiedy użytkownik zapłacił za zamówienie produktu handlowego.Pamiętaj, że zdarzenia webhook duplikatowe są możliwe, więc powinieneś wykluczyć zdarzenia za pomocą unikalnego ID zamówienia handlowego.

Konfiguruj webhooki na pulpicie nawigacyjnym twórcy

Aby otrzymywać powiadomienia za pośrednictwem webhooków, musisz skonfigurować webhook, który subskrybuje pewne wydarzenia, aby uruchomić powiadomienia.W przypadku doświadczeń należących do grupy tylko właściciele grupy mogą skonfigurować i otrzymywać powiadomienia o webhookach.

Jeśli konfigurujesz webhooki i przetwarzasz dane osobowe, upewnij się, że są one zgodne z ogólnym rozporządzeniem o ochronie danych (RODO).

Aby skonfigurować webhook:

Przejdź do sekcji Webhooks na panelu administratora twórcy.
Kliknij przycisk Dodaj webhook .
Ukończ pola konfiguracyjne:
1. URL webhooka - Wskazuj URL, na którym chcesz otrzymywać powiadomienia.Aby uzyskać więcej informacji o wymaganiach, zobacz Ustaw URL-y webhook.
2. Nazwa - Użyj niestandardowej nazwy, aby odróżnić swoją konfigurację od innych. Domyślnie wartość jest taka sama jak URL Webhooka.
3. Sekretny (opcjonalnie) - Dostarcz sekret, jeśli chcesz zweryfikować, czy powiadomienia, które otrzymujesz, pochodzą z Roblox.Aby uzyskać więcej informacji, zobacz Zweryfikuj bezpieczeństwo webhooka.
4. Triggery - Wybierz jedną lub więcej opcji z listy wspieranych triggerów wydarzeń, dla których chcesz otrzymywać powiadomienia.
Kliknij przycisk Zapisz zmiany .

Obecnie możesz skonfigurować do 5 webhooków łącznie.

Ustaw URL-e webhooków

Możesz skonfigurować niestandardowy punkt końcowy usługi HTTP jako swój URL webhook, pod warunkiem spełnienia następujących wymogów:

Musi być publicznie dostępny do obsługi żądań.
Może obsługiwać prośby POST.
Może odpowiedzieć na żądanie odpowiedzią 2XX w ciągu 5 sekund.
Może obsługiwać żądania HTTPS.

Kiedy twój koniec otrzymuje żądanie POST, musi być w stanie:

Wyodrębnij szczegóły wymagane dotyczące powiadomienia z ciała wiadomości POST.
Przeczytaj treść wiadomości POST z ogólnymi szczegółami na temat powiadomienia i szczegółami związanymi z typem wydarzenia w powiadomieniu.

Aby uzyskać więcej informacji o schemacie żądań POST do przetworzenia, zobacz schemat obciążenia.

Polityka ponownego próbowania niepowodzenia dostawy

Kiedy powiadomienie webhook nie może dotrzeć do określonej URL z powodu błędów, takich jak niedostępność punktu końcowego, Roblox ponownie próbuje wysłać wiadomość na określoną URL 5 razy za pomocą stałego rozmiaru okna.Jeśli powiadomienie nadal nie zostanie dostarczone po 5 próbach, Roblox przestaje próbować wysłać powiadomienie i zakłada, że URL nie jest już ważny.W tej sytuacji musisz zaktualizować konfigurację webhooka za pomocą nowego URL, który jest dostępny i może otrzymywać powiadomienia.Aby rozwiązać problemy i potwierdzić, że twój URL webhook może pomyślnie otrzymywać powiadomienia, zobacz Testuj webhooki.

Wymagania stron trzecich

Narzędzia stron trzecich zwykle mają własne wymagania dotyczące webhooków, których musisz przestrzegać przy ustawianiu URL webhook.Możesz znaleźć te wymagania, wyszukując słowo kluczowe "webhook" na stronie wsparcia lub dokumentacji narzędzia docelowego.Dla trzech wspieranych narzędzi stron trzecich zobacz następujące:

Testuj webhooki

Możesz sprawdzić, czy webhook, który skonfigurowałeś, może pomyślnie otrzymywać powiadomienia na Pulpicie nawigacyjnym twórcy:

Przejdź do strony konfiguracji Webhooks.
Wybierz webhook, który chcesz przetestować z listy skonfigurowanych webhooków.
Kliknij ikonę ołówka obok docelowego webhooka.
Kliknij przycisk Odpowiedź testowa .

System wysyła następnie wydarzenie SampleNotification, które zawiera ID użytkownika użytkownika, który uruchomił powiadomienie, jak pokazano tutaj:

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

Jeśli integrujesz swój webhook z usługą strony trzeciej, możesz go przetestować za pomocą URL strony trzeciej, aby potwierdzić, że usługa może pomyślnie otrzymywać powiadomienia z twojego webhooka.Jeśli podasz sekret podczas konfigurowania webhooka, generuje również roblox-signature, którego możesz użyć do testowania logiki roblox-signature.

Zweryfikuj bezpieczeństwo webhooka

Po skonfigurowaniu serwera do odbierania pakietów zaczyna słuchać każdego pakietu wysłanego do końca.Jeśli ustawisz sekret podczas konfiguracji swojego webhooka, Roblox wysyła roblox-signature w każdej powiadomieniu webhook, aby upewnić się, że żądanie pochodzi rzeczywiście z Roblox.Podpis znajduje się w nagłówku pakietu dla niestandardowych punktów końcowych i w stopce dla serwerów stron trzecich.

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

Jeśli nie ustawiłeś sekretu dla swojego webhooka, podpis zawiera tylko czas戳 wysłania powiadomienia:

Signature format without a secret for custom endpoints
t=<timestamp>

Aby zweryfikować podpis:

Wyodrębnij wartości czasu i podpisu.Wszystkie podpisy dla webhooków z sekretami mają ten sam format jak ciąg znaków CSV z tymi dwoma wartościami po prefiksach:
- t : Data i czas przesłania powiadomienia.
- v1 : Wartość podpisu generowana za pomocą sekretu dostarczonego przez konfigurację panelu administratora twórcy.
Odtwórz podstawową strunę roblox-signature poprzez połączenie:
1. Data ważności jako ciąg znaków.
2. Znak okresowy ..
3. Sznurek JSON z ciała żądania.
Wylicz kod autentyzacji wiadomości oparty na haszu (HMAC) za pomocą funkcji haszu SHA256 za pomocą sekretu, który określiłeś podczas konfiguracji jako klucz i strony bazowej, którą wygenerowałeś za pomocą kroku 2 jako wiadomość.Konwertuj wynik do formatu Base64, aby uzyskać oczekiwany podpis.
Porównaj wyodrębnioną wartość podpisu do oczekiwanej podписи. Jeśli wygenerowałeś podpis poprawnie, wartość powinna być taka sama.
(Opcjonalnie) Aby zapobiec atakom odtwarzania, rodzajowi cyberataku, w którym atakujący przechwycają i przesyłają dane, aby uzyskać nieautoryzowany dostęp lub wykonać złośliwe działania, pomocne jest porównanie wartości czasu wyciągnięcia z aktualnym czasem i upewnienie się, że znajduje się ona w rozsądnym limicie czasowym.Na przykład 10-minutowe okno jest zazwyczaj dobrym rozsądnym terminem.

Schema obciążenia

Gdy uruchomione zostanie docelowe wydarzenie webhooka, wysyła żądanie do URL webhooka, w tym informacje o wydarzeniu w zapytaniu.Wszystkie płatności żądań dzielą tę samą schemat, która składa się z stałych i zmiennych pól.Zapewnia to, że dane przesłane w zapleczu są zstrukturyzowane i spójne, co ułatwia odbierającej aplikacji przetwarzanie i wykorzystywanie danych.

Pola schematu ładowania stałe można pomóc utrzymać spójność wśród wszystkich żądań webhook, z następującymi dostępnymi polami:

NotificationId (string): Unikalny identyfikator dla każdej wysłanej notyfikacji. Jeśli otrzymano tę samą NotificationId dwukrotnie, jest to uważane za duplikat.
EventType (string): Wskazuje rodzaj zdarzenia, dla którego uruchomiono powiadomienie.
EventTime (string): Datum czasu, kiedy uruchomiono wydarzenie.

Pole ładowania zmiennej zapewnia elastyczność dla webhooków, aby pomieścić różne rodzaje zdarzeń, które obejmują:

EventPayload (obiekt): Zawiera informacje specyficzne dla EventType, które uruchomiły webhook.Struktura schematu EventPayload zmienia się w zależności od rodzaju zdarzenia.

Poniższy przykład pokazuje schemat obciążenia wydarzenia Prawo do usunięcia żądania :

Przykład schematu dla wniosku o prawo do usunięcia
{
   "NotificationId": "string",
   "EventType": "RightToErasureRequest",
   "EventTime": "2023-12-30T16:24:24.2118874Z",
   "EventPayload": {
      "UserId": 1,
      "GameIds": [
         1234, 2345
      ]
   }
}

Ręczne powiadomienia

Jeśli przechowujesz jakiekolwiek Osobowo identyfikujące informacje (PII) użytkowników, takie jak ich ID użytkownika, musisz usunąć te informacje, gdy użytkownik złoży taką prośbę, aby spełnić wymogi zgodności z RODO prawo do usunięcia.Możesz stworzyć bot, który będzie obsługiwał powiadomienia o webhookach i pomoże zautomatyzować usuwanie danych, pod warunkiem przechowywania PII w magazynie danych.Zobacz Automatyzację praw do żądań usuwania danych dla przykładu na to, jak utworzyć bot w Guilded lub Discord, który wykorzystuje Otwartą chmurkową API dla przechowywania danych, aby usunąć dane PII jako rozwiązanie automatyzacji.Ten przykład można dostosować do obsługi innych powiadomień, takich jak wydarzenia subskrypcyjne.

Jeśli używasz niestandardowego punktu końcowego jako serwer webhook zamiast narzędzia zewnętrznego, możesz wyciągnąć dane podlegające usunięciu z pakietu webhook i zbudować własne rozwiązanie automatyzacji.Poniższy przykład kodu to przykład serwera, który ma zapobieganie atakom odtwarzania poprzez weryfikację czasu trwania i że żądanie pochodzi z Roblox:

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

Na tej stronie