Powiadomienia webhook

Zamiast ręcznie monitorować wszystkie zdarzenia w swoim doświadczeniu i żądania od użytkowników, możesz skonfigurować webhooki, aby otrzymywać powiadomienia w czasie rzeczywistym w zewnętrznym narzędziu do komunikacji lub na własnym punkcie końcowym, który może odbierać zapytania HTTP. Dzięki temu możesz zautomatyzować zarządzanie powiadomieniami, aby zredukować wysiłek związany z obsługą powiadomień.

Przepływ pracy z webhookami

Webhooki wysyłają powiadomienia w czasie rzeczywistym lub dane między dwiema różnymi aplikacjami lub usługami, takimi jak Roblox i narzędzie do komunikacji. W przeciwieństwie do tradycyjnych interfejsów API, które wymagają skonfigurowania aplikacji klienckiej do wysyłania zapytań do serwera w celu otrzymania danych, webhooki wysyłają dane do twojego punktu końcowego, gdy tylko wystąpi zdarzenie. Są one przydatne do automatyzacji przepływu pracy między Robloxem a aplikacjami zewnętrznymi, które używasz do współpracy z zespołem, ponieważ umożliwiają udostępnianie i przetwarzanie danych w czasie rzeczywistym.

Gdy skonfigurujesz webhook, za każdym razem, gdy wystąpi docelowe zdarzenie, Roblox wysyła żądanie na URL webhooka, który dostarczasz. URL webhooka następnie przekierowuje żądanie do Twojej aplikacji odbierającej lub niestandardowego punktu końcowego, który może podjąć działanie na podstawie danych zawartych w ładunku webhooka. Może to obejmować usunięcie danych na podstawie RODO, wysłanie potwierdzenia do użytkownika lub wyzwolenie innego zdarzenia.

Obsługiwane wyzwalacze

Roblox obecnie obsługuje następujące wyzwalacze zdarzeń.

Subskrypcja

• Subskrypcja wznowiona - Gdy użytkownik ponownie subskrybuje subskrypcję, wysyłana jest wiadomość zawierająca subskrypcję i subskrybenta.
• Subskrypcja odnowiona - Gdy użytkownik odnawia subskrypcję, wysyłana jest wiadomość zawierająca subskrypcję i subskrybenta.
• Subskrypcja zwrócona - Gdy użytkownik otrzymuje zwrot za swoją subskrypcję, wysyłana jest wiadomość zawierająca subskrypcję i subskrybenta.
• Subskrypcja zakupiona - Gdy użytkownik kupuje subskrypcję, wysyłana jest wiadomość zawierająca subskrypcję i subskrybenta.
• Subskrypcja anulowana - Gdy użytkownik anuluje subskrypcję, wysyłana jest wiadomość zawierająca subskrypcję i subskrybenta, a także podaną przyczynę anulowania.

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

Zgodność

• Żądanie prawa do usunięcia - Gdy użytkownik składa żądanie usunięcia danych zgodnie z Ogólnym rozporządzeniem o ochronie danych osobowych (RODO).

Handel

• Zamówienie produktu handlowego zwrócone - Gdy użytkownik otrzymuje zwrot za swoje zamówienie na produkt handlowy lub zamówienie zostało anulowane.
• Zamówienie produktu handlowego opłacone - Gdy użytkownik opłaca swoje zamówienie na produkt handlowy. Należy pamiętać, że możliwe są zduplikowane zdarzenia webhook, dlatego należy odfiltrować zdarzenia za pomocą unikalnego identyfikatora zamówienia handlowego.

Konfiguracja webhooków na Kokpicie Twórcy

Aby otrzymywać powiadomienia przez webhooki, musisz skonfigurować webhook, który subskrybuje określone zdarzenia w celu wyzwolenia powiadomień. Dla doświadczeń posiadanych przez grupy tylko właściciele grup mogą konfigurować i otrzymywać powiadomienia webhook.

Aby skonfigurować webhook:

1. Wybierz swoje doświadczenie w Kokpicie Twórcy.

2. W sekcji Konfiguracja wybierz Webhooki i kliknij Dodaj webhook.

   URL webhooka pochodzi od Twojego dostawcy. Na przykład, URL Slacka wygląda prawdopodobnie tak:

   https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX

3. Wprowadź swój URL webhook i nazwę.

4. (Opcjonalnie) Dodaj sekret, co pomoże zapewnić, że powiadomienia, które otrzymujesz, pochodzą z Robloxa. Aby uzyskać więcej informacji, zobacz Weryfikacja bezpieczeństwa webhooka.

5. Wybierz jedną lub więcej opcji z listy obsługiwanych wyzwalaczy zdarzeń, dla których chcesz otrzymywać powiadomienia.

6. (Opcjonalnie) Użyj przycisku Testuj odpowiedź, aby sprawdzić, czy Twoja usługa może odebrać przykładowe zapytanie.

7. Kliknij Zachowaj zmiany.

Ustaw URL webhooków

Możesz ustawić niestandardowy punkt końcowy usługi HTTP jako URL swojego webhooka, pod warunkiem, że spełnia następujące wymagania:

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

Kiedy Twój punkt końcowy otrzymuje zapytanie POST, musi być w stanie:

• Wyodrębnić szczegóły dotyczące powiadomienia z treści wiadomości POST.
• Odczytać treść wiadomości POST ze szczegółami ogólnymi o powiadomieniu oraz szczegółami związanymi z typem zdarzenia w powiadomieniu.

Aby uzyskać więcej informacji o schemacie zapytań POST do obsługi, zobacz Schemat ładunku.

Polityka ponownych prób po niepowodzeniu dostarczania

Gdy powiadomienie webhook nie dotrze do wskazanego URL z powodu błędów, takich jak niedostępność punktu końcowego, Roblox ponownie próbuje wysłać wiadomość na skonfigurowany URL 5 razy, używając 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 o nowy URL, który jest osiągalny i zdolny do odbierania powiadomień. Aby rozwiązać problemy i potwierdzić, że Twój URL webhooka może z powodzeniem odbierać powiadomienia, zobacz Testowanie webhooków.

Wymagania dotyczące narzędzi zewnętrznych

Narzędzia zewnętrzne zazwyczaj mają własne wymagania dotyczące webhooków, których musisz przestrzegać podczas konfigurowania swojego URL webhooka. Możesz znaleźć te wymagania, wyszukując słowo kluczowe "webhook" na stronie wsparcia lub dokumentacji docelowego narzędzia. Dla obsługiwanych narzędzi zewnętrznych, zobacz poniżej:

• Centrum pomocy Discord
• Dokumentacja API Slacka

Testowanie webhooków

Możesz przetestować, czy skonfigurowany przez Ciebie webhook może pomyślnie odbierać powiadomienia na Kokpicie Twórcy:

1. Przejdź do strony konfiguracji Webhooki.
2. Wybierz webhook, który chcesz przetestować, z listy skonfigurowanych webhooków.
3. Kliknij ikonę ołówka obok docelowego webhooka.
4. Kliknij przycisk Testuj odpowiedź.

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

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

Jeśli integrujesz swój webhook z usługą zewnętrzną, możesz przetestować go, używając zewnętrznego URL, aby potwierdzić, że usługa może pomyślnie odbierać powiadomienia z Twojego webhooka. Jeśli podczas konfigurowania webhooka dostarczysz sekret, generuje też roblox-signature, którą możesz użyć do przetestowania logiki roblox-signature.

Weryfikacja bezpieczeństwa webhooka

Po skonfigurowaniu serwera do odbierania ładunków zaczyna on nasłuchiwać na jakiekolwiek ładunki wysyłane do punktu końcowego. Jeśli ustawiłeś sekret podczas konfigurowania swojego webhooka, Roblox wysyła roblox-signature w każdym powiadomieniu webhook, aby upewnić się, że żądanie rzeczywiście pochodzi z Robloxa. Podpis znajduje się w nagłówku ładunku dla niestandardowych punktów końcowych i w stopce dla serwerów zewnętrznych.

Format podpisu z sekretem dla niestandardowych punktów końcowych
t=<timestamp>,v1=<signature>

Jeśli nie ustawiłeś sekretu dla swojego webhooka, podpis zawiera tylko znacznik czasu, kiedy powiadomienie zostało wysłane:

Format podpisu bez sekretera dla niestandardowych punktów końcowych
t=<timestamp>

Aby zweryfikować podpis:

1. Wyodrębnij wartości znaczników czasu i podpisu. Wszystkie podpisy dla webhooków z sekretami mają ten sam format jako ciąg CSV z tymi dwoma wartościami poprzedzonymi prefiksami:

   • t: Znacznik czasu, kiedy powiadomienie zostało wysłane.
   • v1: Wartość podpisu generowana przy użyciu sekretu podanego w konfiguracji Kokpitu Twórcy.

2. Odtwórz podstawowy ciąg roblox-signature, łącząc:

   1. Znacznik czasu jako ciąg.
   2. Znak kropki ..
   3. Ciąg JSON treści żądania.

3. Oblicz kod uwierzytelniania wiadomości oparty na haszach (HMAC) z funkcją haszującą SHA256, używając sekretu zdefiniowanego podczas konfiguracji jako klucza i podstawowego ciągu, który wygenerowałeś w kroku 2, jako wiadomości. Przekonwertuj wynik na format Base64, aby uzyskać oczekiwany podpis.

4. Porównaj wyodrębnioną wartość podpisu z oczekiwanym podpisem. Jeśli poprawnie wygenerowałeś podpis, wartość powinna być taka sama.

5. (Opcjonalnie) Aby zapobiec atakom powtórzeniowym, rodzajowi ataku cybernetycznego, gdzie napastnicy przechwytują i ponownie wysyłają dane, aby uzyskać nieautoryzowany dostęp lub wykonywać złośliwe działania, pomocne jest porównanie wyodrębnionej wartości znacznika czasu z bieżącym znacznikiem czasu i upewnienie się, że mieści się w rozsądnym limicie czasowym. Na przykład, 10-minutowe okno zwykle jest rozsądnym limitem czasowym.

Schemat ładunku

Kiedy docelowe zdarzenie Twojego webhooka zostanie wyzwolone, wysyła żądanie na Twój URL webhooka, w tym informacje o zdarzeniu w ładunku. Wszystkie ładunki zapytań mają ten sam schemat, który składa się z pól stałych i zmiennych. Zapewnia to, że dane przesyłane w ładunku są uporządkowane i spójne, co ułatwia aplikacji odbierającej przetwarzanie i wykorzystywanie danych.

Pola stałe schematu ładunku mogą pomóc w utrzymaniu spójności we wszystkich żądaniach webhook, z następującymi dostępnymi polami:

1. NotificationId (string): Unikalny identyfikator dla każdego wysłanego powiadomienia. Jeśli ten sam NotificationId zostanie otrzymany dwa razy, jest uważany za duplikat.
2. EventType (string): Wskazuje typ zdarzenia, dla którego zostało wyzwolone powiadomienie.
3. EventTime (string): Znacznik czasu, kiedy zdarzenie zostało wyzwolone.

Pola zmienne schematu ładunku zapewniają elastyczność dla webhooków, aby pomieścić różne typy zdarzeń, które obejmują:

1. EventPayload (obiekt): Zawiera informacje specyficzne dla EventType, który wyzwolił webhook. Struktura schematu EventPayload różni się w zależności od rodzaju zdarzenia.

Poniższy przykład pokazuje schemat ładunku dla zdarzenia Żądanie Prawa do Usunięcia:

Przykład schematu dla żądania Prawa do Usunięcia
{
   "NotificationId": "string",
   "EventType": "RightToErasureRequest",
   "EventTime": "2023-12-30T16:24:24.2118874Z",
   "EventPayload": {
      "UserId": 1,
      "GameIds": [
         1234, 2345
      ]
   }
}

Obsługa powiadomień

Jeśli przechowujesz jakiekolwiek Informacje Osobowe (PII) swoich użytkowników, takie jak ich identyfikatory użytkowników, musisz usunąć te informacje, gdy użytkownik złoży takie żądanie, aby spełnić wymagania dotyczące zgodności RODO prawo do usunięcia. Możesz stworzyć bota do obsługi powiadomień webhooków i pomóc w automatyzacji usuwania danych, pod warunkiem, że przechowujesz PII w bazie danych. Zobacz Automatyzacja usuwania żądań Prawa do Usunięcia, aby uzyskać przykład, jak stworzyć bota w Discordzie, który wykorzystuje Open Cloud API dla baz danych do usuwania danych PII jako rozwiązanie automatyzacyjne. Ten przykład można dostosować do obsługi innych powiadomień, takich jak zdarzenia subskrypcyjne.

Jeśli używasz niestandardowego punktu końcowego jako swojego serwera webhook zamiast narzędzia zewnętrznego, możesz wyodrębnić dane do usunięcia z ładunku webhooka i zbudować własne rozwiązanie automatyzacyjne. Poniższy przykładowy kod to przykład serwera, który ma ochronę przed atakami powtórzeniowymi, weryfikując znacznik czasu oraz to, że żądanie pochodzi z Robloxa:

Wyodrębnianie PII z ładunku
const crypto = require('crypto');
const express = require('express');

const secret = '<your_secret>' // Można ustawić jako zmienną środowiskową

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

app.all('/*', function (req, res) {
   console.log('Nowe żądanie odebrane');

   // Wyodrębnij znacznik czasu i podpis z nagłówka
   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);

   // Upewnij się, że żądanie pochodzi w oknie 300 sekundowym, aby zapobiec atakom powtórzeniowym
   const requestTimestampMs = timestamp * 1000;
   const windowTimeMs = 300 * 1000;
   const oldestTimestampAllowed = Date.now() - windowTimeMs;

   if (requestTimestampMs < oldestTimestampAllowed) {
      return res.status(403).send('Wygasłe żądanie');
   }

   // Weryfikacja podpisu
   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('Nieautoryzowane żądanie');
   }

   // Twoja logika do obsługi ładunku
   const payloadBody = req.body;
   const eventType = payloadBody['EventType'];

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

      console.log(`Dane ładunku: UserId=${userId} i GameIds=${gameIds}`);
      // Jeśli przechowujesz PII w bazach danych, użyj UserId i GameIds, aby usunąć informacje z baz danych.
   }

   return res.json({ message: 'Pomyślnie przetworzono wiadomość' });
});

app.listen(8080, function () {
   console.log('Serwer uruchomiony');
});