Zamiast ręcznie monitorować wszystkie wydarzenia w swoim doświadczeniu i wnioski od użytkowników, możesz ustawić webhooki do otrzymywania prawdziwych czasowych powiadomień na narzędziach wiadomościach stron trzecich lub na swoim własnym końcu, który może otrzymywać wnioski HTTP. To pomaga automatyzować twoją pracę nad powiadomieniami, aby zmniejszyć ręczne wysyłanie powiadomień.
Obecnie Roblox w pełni wspiera powiadomienia o webhookach dla Discord, Guilded i Slack. Używanie webhooków z innymi narzędziami trzecim stronnym ryzykuje nie otrzymywania wszystkich powiadomień.
Przepływ pracy Webhook
Webhook wysyłają prawdziwe notyfikacje lub dane między dwoma różnymi aplikacjami lub usługami, takimi jak Roblox i narzędzie do wysyłania wiadomości stron trzecich. W przeciwieństwie do zwykłych API, które wymagają ustawienia klienta do wysyłania żądań na serwer, aby otrzymać dane, w
Gdy ustawisz webhook, wysyłając na niego wszystkie wydarzenia związane z celem, Roblox wysyła wniosek do URL webhook, który zapewniać. Wniosek zostanie wtedy przekierowany do twojego odbiorczego aplikatu lub własnego końca, co może zostać zainicjowane w oparciu o dane zawarte w webhook. To może obejmować usuwanie danych dla celu, wysyłanie potwierdzeń dla
Wspierane przez
Roblox obecnie wspiera następujące zdarzenia dla powiadomień:
- Subscription Cancelled - Kiedy użytkownik anuluje subskrypcję, wiadomość zostanie wysłana zawierająca subskrypcję i subskrybenta, a także powód anulowania.
- Subscription Purchased - Kiedy użytkownik kupuje subskrypcję, wiadomość zostanie wysłana zawierająca subskrypcję i subskrybenta.
- Subscription Refunded - Gdy użytkownik otrzymuje pieniądze za subskrypcję, wiadomość zawiera subskrypcję i subskrybenta.
- Subscription Renewed - Kiedy użytkownik odnawia subskrypcję, wiadomość jest wysyłana zawierająca subskrypcję i subskrybenta.
- Subscription Resubscribed - Gdy użytkownik ponownie subskrybuje subskrypcję, wiadomość zostaje wysłana zawierająca subskrypcję i subskrybenta.
- „Prawo do bycia zapomnianym” wnioski o usunięcie danych zgodnie z ogólnym rozporządzeniem o ochronie danych ( GDPR ).
Dla więcej informacji na temat wydarzeń subskrypcji i ich polach, zobacz referencję Cloud API Subscription.
Konfigurowanie wtyczek witryny na Panelu twórcy
Aby otrzymywać powiadomienia za pośrednictwem webhooków, musisz skonfigurować webhook, który subskrybuje pewne wydarzenia, aby zainicjować powiadomienia. Dla doświadczeń własności grupy tylko właściciele grup mogą skonfigurować i otrzymywać powiadomienia webhook.
Jeśli ustawiasz webhooki i przetwarzasz dane osobowe, upewnij się, że zgodnie z ogólnym rozporządzeniem o ochronie danych (RODO).
Aby skonfigurować węzę sieci:
- Przejdź do sekcji Webhooki w Panelu twórcy.
- Kliknij przycisk Dodaj Webhook .
- Ukończ pola konfiguracji:
- URL webhook'a — Wpisz URL, do którego chcesz otrzymywać powiadomienia i akceptować przychodzące wiadomości webhook od podmiotów zewnętrznych. Dla więcej informacji o wymaganiach, zobacz Ustawienie webhook'a URL.
- Imię — Użyj ustalonego imienia, aby odróżnić swoją konfigurację od innych. Domyślnie wartość jest taka sama jak URL Webhook.
- Sekretowy (opcjonalny) — Dostarcz sekret, jeśli chcesz sprawdzić, czy otrzymywane przez ciebie powiadomienia pochodzą od Roblox. Aby uzyskać więcej informacji, zobacz Zweryfikowanie bezpieczeństwa Webhook.
- Triggery — Wybierz jeden lub więcej opcji z listy obsługiwanych triggerów wydarzeń, dla których chcesz otrzymywać powiadomienia.
- Kliknij przycisk Zapisz zmiany .
Obecnie możesz skonfigurować do 5 włączników webhooków w całej.
Ustawianie URL w Webhook
Możesz ustawić niestandardowy URL serwera HTTP jako swoją URL wtyczki, o ile spełnia następujące wymagania:
- Musi być publicznie dostępny do przetwarzania wniosków.
- Może obsługiwać wnioski POST.
- Może odpowiedzieć na wniosek za pomocą odpowiedzi 2XX w ciągu 5 sekund.
- Może obsługiwać wnioski HTTPS.
Gdy twój końcowy odbiera prośbaPOST, musi być w stanie:
- Ekstraktuj szczegóły wymagane o powiadomieniu z ciała wiadomości POST.
- Przeczytaj ciało wiadomości POST z genéricznymi szczegółami na powiadomieniu i szczegółami związanymi z typem wydarzenia na powiadomienie.
Dla więcej informacji o schemacie wnętrznych prośb POST do zarządzania, zobacz Payload Schema.
Polityka ponownego dostarczania błędu
Gdy webhook notification nie dotrze do Twojego określonego URL z powodu błędów, takich jak niedostępność końca, Roblox ponownie wysyłając wiadomość do konfigurowanego URL 5 razy używając stałego rozmiaru okna. Jeśli wiadomość nadal nie zostanie dostar
Wymagania stron trzecich
Narzędzia stron trzecich zwykle mają własne wymagania dotyczące webhook'ów, które musisz podążać, gdy ustawiasz URL swojego webhook'a. Możesz znaleźć te wymagania poprzez szukanie słowa kluczowego "webhook" na stronie wsparcia lub dokumentacji celu. Dla trzech wspieranych narzędzi stron trzecich, zobacz obserwuje:
Testowanie Webhooków
Możesz sprawdzić, czy wtyczka witryny, którą skonfigurowałeś, może otrzymywać powiadomienia na Panelu twórcy :
Przejdź do strony konfiguracji Webhooków.
Wybierz webhook, który chcesz przetestować z listy skonfigurowanych webhooków.
Kliknij ikonę ołówka obok celu włączenia.
Kliknij przycisk Odpowiedź na test .
Następnie system wysyła powiadomienie w rodzaju SampleNotification, które zawiera identyfikator użytkownika użytkownika, który wywołuje powiadomienie, jak pokazano w następującej schemacie przykładu:
Schema powiadomień
Body: {
"NotificationId": "string",
"EventType": "SampleNotification",
"EventTime": "2023-12-30T16:24:24.2118874Z", // Typ: Czas odpowiadający ISO 8601
"EventPayload": {
"UserId": 1 // Typ: Długi
}
}
Jeśli wdrożysz swoją wtyczkę witryny z usługą stron trzecich, możesz ją przetesterować za pomocą trzeciego partyjnego URL, aby potwierdzić, że usługa może otrzymywać powiadomienia z wtyczki witryny z sukcesem. Jeśli dostarczysz sekret podczas konfiguracji wtyczki, generuje on również roblox-signature, którą
Zweryfikowanie bezpieczeństwa wtyczki
Gdy skonfigurujesz swój serwer, aby otrzymywać ładowania, zaczyna słuchać dowolnego ładowania wysłanego do końca. Jeśli ustawisz sekret podczas konfiguracji swojego webhook, Roblox wysyła roblox-signature wraz z każdą powiadomieniem o webhook,
Signature Format with Secret for Custom Endpoints
Jeśli nie masz sekretu dla swojego webhook, podpis, który otrzymujesz, zawiera tylko wartość czasu na wysłanie powiadomienia:
Signature Format without Secret for Custom Endpoints
Aby zweryfikować podpis:
Ekstraktuj znacznik czasu i wartości podpisu. Wszystkie znaczniki dla webhooków z sekretami dzielą się tą samą formatacją co CSV strzałka z tych dwóch wartości po zapisach:
- t : Wartość czasu ustawiona na czas wysyłania powiadomienia.
- v1 : Wartość podpisu generowana przy użyciu sekretu dostarczonego przez konfigurację Dashboardu Twórcy. Możesz wyodrębnić te dwa wartości przy użyciu funkcji split() ", która oddziela stronę opartą na delimitatorze, w tym przypadku znaku ,.
Odnowić podstawową linię roblox-signature poprzez połączenie:
- Czas użycia jako ciąg stron.
- Znak okresu . .
- String JSON w ciele ciało.
Oblicz kod uwierzytelnienia wiadomości oparty na haszu (HMAC) z użyciem funkcji haszowania secret, którą określiłeś podczas konfiguracji jako klucz i bazową strungę, którą generowałeś za pośrednictwem kroku 2 jako wiadomość. Konwertuj wynik do formatu Base64, aby uzyskać oczekiwany podpis.
Porównaj wartość podpisu wyciągniętego do oczekiwanego podpisu. Jeśli generowałeś podpis poprawnie, wartość powinna być taka sama.
(Opcjonalnie) Aby zapobiec atakom na powtórkę, typ cyberataku, w którym atakujący odbierają i wysyłają dane, aby uzyskać nieautoryzowany dostęp lub wykonują niechciane działania, pomocne jest porównanie wartości czasu odtwarzania z aktualnym czasem odtwarzania i zapewnienie, że upływa w rozsądny czas limit. Na przykład 10-minutowe okno jest zwykle dobrym rozsądnym czasem limitem.
Schemat płatności
Gdy wydarzenie docelowe twojego webhook'a zostanie wywołane, wysyła prośbę o twój webhook, w tym informacje o wydarzeniu w ładowaniu. Wszystkie ładowania wniosków dzielą się tą samą schemas, która składa się z zmienne i stałe pola. To zapewnia, że dane przesłane w ładowaniu są strukturalne i spójne, ułatwiając łatwiejsze przetwarzanie i używanie danych.
Pole 固定 payload schema może pomóc utrzymać spójność w wszystkich wnioskach webhook, z następującymi polami dostępnymi:
- NotificationId , string : Unikalny identyfikator dla każdej wysłanej notyfikacji. Jeśli ten sam NotificationId jest otrzymywany dwa razy, jest to uważany za duplikat.
- EventType , string : Strings są reprezentowane przez typ wydarzenia, dla którego powiadomienie zostało uruchomione.
- EventTime , timestamp : Około daty uruchomienia wydarzenia.
Pole schemas obciążeń Variable Loaded Hooks umożliwia elastyczność dla wszystkich rodzajów wydarzeń, które obejmują:
- EventPayload , object : Contains information specific to the EventType that triggered the webhook. The structure of the 0> EventPayload0> schema varies based on the type of event.
Poniższy przykład pokazuje schemat ładowania Right To Erasure Request wydarzenia:
Example Schema for Prawo do żądania usunięcia danych
Body:{
"NotificationId": "string",
"EventType": "RightToErasureRequest",
"EventTime": "2023-12-30T16:24:24.2118874Z",
"EventPayload": {
"UserId": 1, // Typ: Długi
"GameIds": [ // Typ: Arrays długości
1234, 2345
]
}
}
Przyczepianie Notyfikacji
Jeśli przechowujesz jakiekolwiek dane osobowo-identyfikujące swoich użytkowników, takie jak ich identyf
Jeśli użyjesz niestandardowego końca jako swojego serwera wtyczki wraz z usługą webhook, możesz wyodrębnić dane przedmiotu do usunięcia z webhook'a i zbudować własne rozwiązanie automatyzacji. Poniższy kod przykładowy dostarcza przykładowe rozwiązanie i dodaje zapobieganie powtarzania ataków, poprzez zweryfikowanie, ż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')
})