Powiadomienia webhook

Zamiast ręcznie monitorować wszystkie zdarzenia w swojej grze i żądania od użytkowników, możesz skonfigurować webhooki, aby otrzymywać powiadomienia w czasie rzeczywistym w narzędziu do przesyłania wiadomości innych firm lub na własnym punkcie końcowym, który może odbierać żądania HTTP. Pomaga to zautomatyzować zarządzanie powiadomieniami, aby zredukować ręczny wysiłek związany z obsługą powiadomień.

Przepływ pracy webhook

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

Po skonfigurowaniu webhooka, gdy wystąpi zdarzenie docelowe, Roblox wysyła żądanie do podanego przez Ciebie adresu URL webhooka. Adres URL webhooka następnie przekierowuje żądanie do twojej aplikacji odbierającej lub własnego punktu końcowego, który może podjąć działania na podstawie danych zawartych w ładunku webhooka. Może to obejmować usunięcie danych w celu zgodności z RTBF, wysłanie potwierdzenia do użytkownika lub wywołanie innego zdarzenia.

Obsługiwane wyzwalacze

Roblox obecnie wspiera następujące wyzwalacze zdarzeń.

Subskrypcja

• Subskrypcja ponownie subskrybowana - 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ść

• Prawo do usunięcia / Żądanie usunięcia - Gdy użytkownik korzysta ze swojego prawa do trwałego usunięcia swoich danych osobowych zgodnie z obowiązującymi globalnymi przepisami o ochronie danych i prywatności. Więcej informacji można znaleźć w RTBF i twórcy.

Handel

• Zamówienie produktu handlowego zwrócone - Gdy użytkownik otrzymał zwrot za swoje zamówienie produktu handlowego lub zamówienie zostało anulowane.
• Zamówienie produktu handlowego opłacone - Gdy użytkownik opłacił swoje zamówienie produktu handlowego. Należy pamiętać, że możliwe są duplikaty zdarzeń webhook, dlatego należy usunąć duplikaty zdarzeń, używając unikalnego identyfikatora zamówienia handlowego.

Konfiguracja webhooków na pulpicie twórcy

Aby otrzymywać powiadomienia za pośrednictwem webhooków, musisz skonfigurować webhook, który subskrybuje określone zdarzenia do wyzwalania powiadomień. W przypadku gier należących do grupy tylko właściciele grupy mogą konfigurować i odbierać powiadomienia webhook.

Aby skonfigurować webhook:

1. Wybierz swoje doświadczenie na Creator Hub.

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

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

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

3. Wprowadź swój adres URL webhooka i nazwę.

4. OPCJONALNE

   Dołącz sekret, który pomaga zapewnić, że powiadomienia, które otrzymujesz, pochodzą z Robloxa. Więcej informacji znajdziesz w Weryfikacja bezpieczeństwa webhooka.

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

6. OPCJONALNE

   Użyj przycisku Testuj odpowiedź, aby sprawdzić, czy twoja usługa może odebrać przykładowe żądanie.

7. Kliknij Zapisz zmiany.

Ustaw adresy URL webhooków

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

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

Gdy twój punkt końcowy otrzyma żądanie POST, musi być w stanie:

• Wyodrębnić szczegóły wymagane dotyczące powiadomienia z treści wiadomości POST.
• Odczytać treść wiadomości POST z ogólnymi szczegółami na temat powiadomienia i szczegółami specyficznymi dla typu zdarzenia w powiadomieniu.

Aby uzyskać więcej informacji na temat schematu żądań POST do obsługi, zobacz Schemat ładunku.

Polityka ponawiania niepowodzeń dostawy

Gdy powiadomienie webhook nie może dotrzeć do podanego adresu URL z powodu błędów, takich jak niedostępność punktu końcowego, Roblox ponawia próbę wysłania wiadomości do skonfigurowanego adresu 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 adres URL nie jest już ważny. W tej sytuacji musisz zaktualizować konfigurację swojego webhooka o nowy adres URL, który jest osiągalny i może odbierać powiadomienia. Aby rozwiązać problemy i potwierdzić, że twój adres URL webhooka może pomyślnie odbierać powiadomienia, zobacz Testowanie webhooków.

Wymagania dotyczące narzędzi innych firm

Narzędzia innych firm zazwyczaj mają własne wymagania dotyczące webhooków, które musisz przestrzegać podczas konfigurowania swojego adresu 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 innych firm 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 Pulpicie 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 wtedy zdarzenie SampleNotification, które zawiera ID użytkownika użytkownika, który wywołał powiadomienie, jak pokazano tutaj:

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

Jeśli integrujesz swój webhook z usługą innych firm, możesz przetestować go, używając adresu URL tej usługi, aby potwierdzić, że usługa może pomyślnie odbierać powiadomienia z twojego webhooka. Jeśli podczas konfigurowania webhooka podasz sekret, generuje on również roblox-signature, której 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 wszelkie ł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 faktycznie pochodzi z Robloxa. Podpis znajduje się w nagłówku ładunku dla niestandardowych punktów końcowych i w stopce dla serwerów innych firm.

t=<timestamp>,v1=<signature>

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

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 wygenerowana przy użyciu sekretu podanego w konfiguracji Pulpitu 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, który zdefiniowałeś podczas konfiguracji jako klucz i podstawowy ciąg, który wygenerowałeś w kroku 2 jako wiadomość. 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. OPCJONALNE

   Aby zapobiec atakom powtórzeniowym, rodzaj ataku cybernetycznego, w którym napastnicy przechwytują i ponownie wysyłają dane, aby uzyskać nieautoryzowany dostęp lub wykonać 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 jest zazwyczaj dobrym rozsądnym limitem czasowym.

Schemat ładunku

Gdy docelowe zdarzenie twojego webhooka jest wyzwalane, wysyła żądanie do twojego adresu URL webhooka, w tym informacje o zdarzeniu w ładunku. Wszystkie ładunki żądań 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 wykorzystanie danych.

Pola stałego 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 odebrany 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 zmiennego 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óre wyzwoliły webhook. Struktura schematu EventPayload różni się w zależności od typu zdarzenia.

Poniższy przykład pokazuje schemat ładunku dla zdarzenia Żądanie 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 Dane Osobowe (PII) swoich użytkowników, takie jak ich identyfikatory użytkowników, powinieneś ocenić żądanie w świetle swoich obowiązków prawnych. Więcej informacji można znaleźć w RTBF i twórcy. Możesz stworzyć bota do obsługi powiadomień webhook i pomóc w automatyzacji usuwania danych, pod warunkiem, że przechowujesz PII w magazynie danych. Zobacz Automatyzacja usuwania żądań prawa do usunięcia jako przykład, jak stworzyć bota w Discordzie, który używa Open Cloud API dla magazynów danych do usuwania danych PII jako rozwiązania automatyzacyjnego. 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 innych firm, możesz wyodrębnić dane podlegające usunięciu z ładunku webhooka i zbudować własne rozwiązanie automatyzacyjne. Poniższy przykład kodu to przykład serwera, który ma zabezpieczenia przed atakami powtórzeniowymi, weryfikując znacznik czasu i to, że żądanie pochodzi z Robloxa:

const crypto = require('crypto');
const express = require('express');

const secret = '<your_secret>' // To może być ustawione jako zmienna środowiskowa

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

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

   // 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 przyszło w ciągu 300 sekund, 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 magazynach danych, użyj UserId i GameIds, aby usunąć informacje z magazynów danych.
   }

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

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