Powiadomienia Webhook

Zamiast ręcznie monitorować wszystkie wydarzenia w swoim doświadczeniu i prośby 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 punktzie 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 zapewniać.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

Obecnie Roblox wspiera następujące uruchomienia zdarzeń dla powiadomień:

Subskrypcja anulowana - Kiedy użytkownik anuluje subskrypcję subskrypcję, wysyłana jest wiadomość zawierająca subskrypcję i subskrybenta, a także powód anulowania.
Subskrypcja zakupiona - Kiedy użytkownik kupuje 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 odnowiona - Kiedy użytkownik odnawia subskrypcję, wysyłana jest wiadomość zawierająca subskrypcję i subskrybenta.
Subskrypcja odnowiona - Kiedy użytkownik odnowi subskrypcję, wysyłana jest wiadomość zawierająca subskrypcję i subskrybenta.
"Prawo do bycia zapomnianym" wnioski o usunięcie danych zgodnie z ogólnym rozporządzeniem o ochronie danych ( RODO ).

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

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 — Określ URL, na którym chcesz otrzymywać powiadomienia i akceptować przychodzące URL-e webhooków od podmiotów zewnętrznych.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 prośbaPOST, musi być w stanie:

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

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

Polityka ponownego próbowania niepowodzenia polityka

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 obserwuje:

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 powiadomienie w wpisywaćSampleNotification, które zawiera ID użytkownika użytkownika, który uruchamia powiadomienie, jak pokazuje poniższy przykład schematu:

Schema powiadomienia próbnego
Body: {
  "NotificationId": "string",
  "EventType": "SampleNotification",
  "EventTime": "2023-12-30T16:24:24.2118874Z", // Typ: ISO 8601 Timestamp
  "EventPayload": {
    "UserId": 1 // Typ: Długi
  }
}

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 wraz z każdą powiadomieniem webhooka, aby pomóc chronić bezpieczeństwo danych.W ten sposób możesz użyć go, aby zweryfikować, że powiadomienie pochodzi z Roblox i ograniczyć swój serwer do otrzymywania wyłącznie żądań pochodzących 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 Secret for Custom Endpoints
"roblox-signature": "t=<timestamp>,v1=<signature>"

Jeśli nie masz sekretu dla swojego webhooka, podpis, który otrzymujesz, zawiera tylko wartość czasu nadania, gdy wysyłana jest powiadomienie:

Signature Format without Secret for Custom Endpoints
"roblox-signature": "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 : Wartość czasu stemplowania, gdy wysyłana jest powiadomienie.
- v1 : Wartość podpisu generowana za pomocą sekretu dostarczonego przez konfigurację panelu administratora twórcy.Możesz wyciągnąć te dwie wartości za pomocą funkcji split(), która oddziela ciąg za pomocą znacznika, w tym przypadku znaku ,.
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łożądania.
Wylicz kod autoryzacji 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 ta sama NotificationId otrzymuje dwa razy, jest uważana za duplikat.
EventType , string : Ciąg reprezentuje rodzaj zdarzenia, dla którego uruchomiono powiadomienie.
EventTime , timestamp : Około czasoprzestrzenny wskazujący, kiedy uruchomiono wydarzenie.

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

EventPayload , object : 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 żądania usunięcia :

Przykład schematu wniosku o prawo do usunięcia
Body:{

   "NotificationId": "string",

   "EventType": "RightToErasureRequest",

   "EventTime": "2023-12-30T16:24:24.2118874Z",

   "EventPayload": {

      "UserId": 1, // Typ: Długi

      "GameIds": [ // Typ: Tablica długości

         1234, 2345

      ]

   }

}

Ręczne powiadomienia

Jeśli przechowujesz jakiekolwiek Osobowo identyfikujące informacje (dane osobowe) 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 utworzyć bot, który będzie obsługiwał powiadomienia o webhookach i pomoże zautomatyzować usuwanie danych, pod warunkiem przechowywania PII w sklepdanych.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 dostarcza przykładowe rozwiązanie i dodaje zapobieganie atakom odtwarzania, poprzez weryfikację, że żądanie pochodzi z Roblox:

Extracting PII from Payload
const crypto = require('crypto')
const express = require('express');
let app = express();
app.use(express.json());
app.use(express.urlencoded({ extended: true }));
// This is a sample only code
app.all('/*', function (req, res) {
   console.log('-------- New Request Seen -------');
   // 1. Extract the timestamp and signature
   const shared_secret = '<Your secret>' // This can be set as an environment variable
   const hmac = crypto.createHmac('sha256', shared_secret)
   const roblox_signature_header = req.headers['roblox-signature'].split(',')
   // 'roblox-signature' is present in all requests:
   // Timestamp(t) is present in all requests, however signature value(v1) is not set unless a secret is shared during the webhook configuration.
   // Fetch header component at Index 0 -> 't=' and Index 1 -> 'v1='
   const timestamp = roblox_signature_header.find(e => e.startsWith('t=')).substring(2);
   const extracted_signature = roblox_signature_header.find(e => e.startsWith('v1='));
   // 2. Prevent Replay attack: 300 seconds window
   const request_timestamp_ms = timestamp * 1000;
   const window_time_ms = 300 * 1000
   const oldest_timestamp_allowed = Date.now() - window_time_ms;
   if (request_timestamp_ms < oldest_timestamp_allowed) {
      res.status(403).send('Expired Request')
   }
   // 3. Validate Signature
   if (extracted_signature !== undefined) {
      const signature_v1 = extracted_signature.substring(3);
      const message = `${timestamp}.${JSON.stringify(req.body)}`
      const base64_signature = hmac.update(message).digest('base64')
      if (signature_v1 !== base64_signature) {
         res.status(401).send('Unauthorized Request')
      }
   }
   // 4. 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']
      const gameIdString = gameIds.toString()
      console.log(`The payload: UserId=${userId} and GameIds=${gameIdString}`)
      // If you store PII in data stores, use the UserId and GameIds to make a data store call to delete the information.
   }
   // 5. Return Response
   res.json({ message: 'Processed the message Successfully' });
})
app.listen(8080, function () {
   console.log('This is a Sample application')
})

Na tej stronie