Webhook bildirimleri

Deneyiminizdeki tüm olayları ve kullanıcıların isteklerini manuel olarak izleme yerine, üçüncü taraf mesajlaşma aracı veya HTTP isteği alabilen özel noktanız üzerinde gerçek zaman bildirimleri almak için webhook ayarlayabilirsiniz.Bu, bildirim yönetim iş akışınızı otomatikleştirmenize yardımcı olur ve manuel çabayla başa çıkan bildirimleri azaltır.

Şu anda, Roblox tamamen Discord, Guilded ve Slack için webhook bildirimlerini destekliyor.Diğer üçüncü taraf araçlarıyla webhook kullanmak, tüm bildirimleri almama riskini taşır.

Webhook iş akışı

Webhook'lar, Roblox ve üçüncü taraf mesajlaşma aracı gibi iki farklı uygulama veya hizmet arasında gerçek zaman bildirimleri veya veriler gönderir.Geleneksel API'lerden farklı olarak, verileri almak için bir sunucuya istek göndermek için bir istemci uygulaması kurmanızı gerektirenler, webhooklar, bir olay meydana geldiğinde müşteri uç noktanıza veri gönderirler.Roblox ile işbirliği yapmak için kullandığınız Roblox ve üçüncü taraf uygulamaları arasındaki iş akışlarını otomatikleştirmek için yararlıdır, çünkü gerçek zamanlı veri paylaşımına ve işlemine izin verirler.

Bir webhook ayarladıktan sonra, hedef olay meydana geldiğinde, Roblox sağladığınız webhook URL'sine bir istek gönderir.Webhook URL'si ardından istek alan uygulamanıza veya özel uç noktaya yönlendirir, ki bu da webhook yükünün içerdiği verilere dayanarak eylem alabilir.Buna GDPR için verileri silmek, kullanıcıya bir onay göndermek veya başka bir olayı tetiklemek dahil olabilir.

Desteklenen tetikleyiciler

Roblox şu anda aşağıdaki etkinlik tetikleyicilerini destekliyor.

Abonelik

Abonelik yeniden abone edildi - Bir kullanıcı bir aboneliğe yeniden abone olduğunda, abonelik ve abone içeren bir mesaj gönderilir.
Abonman yenilendi - Bir kullanıcı bir aboneliği yenilediğinde, abonelik ve abone içeren bir mesaj gönderilir.
Abonelik İadesi Yapıldı - Bir kullanıcı abonelikleri için bir geri ödeme aldığında, abonelik ve abone içeren bir mesaj gönderilir.
Abonelik Satın Alındı - Bir kullanıcı abonelik satın aldığında, abonelik ve abone içeren bir mesaj gönderilir.
Abonelik İptal Edildi - Bir kullanıcı bir aboneliği iptal ettiğinde, abonelik ve abone ile birlikte verilen neden içeren bir mesaj gönderilir.

Abonelik olayları ve alanları hakkında daha fazla bilgi için Abonelik referansına bakın.

Uyumluluk

Silme İsteğine Hakkı - Bir kullanıcı, Genel Veri Koruma Yönetmeliği (GDPR) altında bir veri silme isteği gönderdiğinde.

Alışveriş

Ticaret ürünü siparişi iade edildi - Bir kullanıcı ticaret ürünü siparişi için bir geri ödeme aldı veya sipariş iptal edildi.
Ticaret Ürün Siparişi Ödenmiştir - Bir kullanıcı ticaret ürün siparişini ödediğinde.Lütfen aynı webhook etkinliklerinin mümkün olduğunu unutmayın, bu yüzden benzersiz ticaret siparişi kimliğini kullanarak etkinlikleri kopyalamalısınız.

Yaratıcı Panosunda webhook'ları yapılandırın

Webhooklar aracılığıyla bildirim almak için, bildirimleri tetiklemek için belirli olaylara abone olan bir webhook yapılandırmanız gerekir.Grup sahibi deneyimler için, sadece grup sahipleri webhook bildirimlerini yapılandırabilir ve alabilir.

Webhook'ları ayarlıyor ve kişisel verileri işliyorsanız, Genel Veri Koruma Yönetmeliğine (GDPR) uyduklarından emin olun.

Bir webhook kurmak için:

Yaratıcı Panosunun Webhookler bölümüne geçiş yapın.
Webhook Ekle düğmesine tıklayın.
Yapılandırma alanlarını tamamla:
1. Webhook URL'si - Bildirim almak istediğiniz URL'yi belirtin.Gereksinimlerle ilgili daha fazla bilgi için, Webhook URL'lerini ayarla bakın.
2. İsim - Yapılandırmanızı diğerlerinden ayırmak için özel bir isim kullanın. Varsayılan olarak değer, Webhook URL'si ile aynıdır.
3. Gizli (isteğe bağlı) - Almış olduğunuz bildirimlerin Roblox'tan geldiğini doğrulamak istiyorsanız bir gizem sağlayın.Daha fazla bilgi için, Webhook güvenliğini doğrula bakın.
4. Tetikleyiciler - Bildirim almak istediğiniz olayların desteklenen tetikleyiciler listesinden bir veya daha fazla seçenek seçin desteklenen tetikleyiciler .
Değişiklikleri Kaydet düğmesine tıklayın.

Şu anda, toplamda en fazla 5 webhook yapılandırabilirsiniz.

Webhook URL'leri kurulduğunda

Webhook URL'niz olarak özel bir HTTP hizmeti sonucu ayarlayabilirsiniz, şu koşullar yerine getirildiği sürece:

Talepleri işlemek için halka açık olmalıdır.
POST isteklerini işleyebilir.
Talebe 5 saniye içinde bir 2XX yanıtıyla yanıt verebilir.
HTTPS isteklerini işleyebilir.

Uç noktanız bir POST isteği aldığında, şunları yapabilmelidir:

Bildirimle ilgili gerekli detayları POST mesajının vücudundan çıkarın.
Bildirimdeki genel ayrıntılar ve bildirimdeki olay türüyle ilgili özel ayrıntılar ile POST mesajının gövdesini okuyun.

POST isteklerini işlemek için çerçevenin daha fazla bilgisi için bakınız: Yük Şeması .

Teslimat başarısızlığı yeniden deneme politikası

Bir webhook bildirimi, uç nokta kullanılabilirliği gibi hatalar nedeniyle belirtilen URL'ye ulaşamadığında, Roblox, sabit bir pencere boyutu kullanarak 5 kez belirtilen URL'ye mesaj göndermeyi yeniden deneyecektir.Eğer bildirim hâlâ 5 denemeden sonra teslim edilemediyse, Roblox bildirimi göndermeyi bırakır ve URL'nin artık geçerli olmadığını varsayar.Bu durumda, webhook yapılandırmanızı yeni bir URL ile güncellemeniz ve ulaşılabilir ve bildirim alabilen bir URL ile alabilmeniz gerekir.Webhook URL'nizin başarıyla bildirim alabileceğini sorun gidermek ve doğrulamak için, Test webhooklarına bakın.

Üçüncü taraf gereksinimleri

Üçüncü taraf araçların genellikle webhook URL'nizi ayarlarken takip etmeniz gereken webhook gereksinimleri vardır.Hedef aracının destek veya belgeler sitesinde "webhook" anahtar kelimesini arayarak bu gereksinimleri bulabilirsiniz.Üç desteklenen üçüncü taraf aracı için, aşağıdakilere bakın:

Test webhook'ları

Yapılandırdığınız webhook'un Yaratıcı Panosu üzerinde başarıyla bildirim alabileceğini test edebilirsiniz:

Navigate to the Webhookler yapılandırma sayfasına.
Konfigürasyonlu webhookler listesinden test etmek istediğiniz webhook'u seçin.
Hedef webhook'un yanındaki kalem simgesine tıklayın.
Test Yanıtı düğmesine tıklayın.

Sistem ardından bir SampleNotification etkinliği gönderir, ki bunun içinde bildirimi tetikleyen kullanıcının Kullanıcı Kimliği dahil edilir, burada gösterildiği gibi:

Örnek Bildirim şeması
{
  "NotificationId": "string",
  "EventType": "SampleNotification",
  "EventTime": "2023-12-30T16:24:24.2118874Z",
  "EventPayload": {
    "UserId": 1
  }
}

Webhook'unuzu üçüncü taraf bir hizmetle entegre ediyorsanız, hizmetin webhook'unuzdan başarıyla bildirim alabileceğini doğrurmak için üçüncü taraf URL'sini kullanarak test edebilirsiniz.Webhook'u yapılandırırken bir sır veriyorsanız, ayrıca roblox-signature test etmek için kullanabileceğiniz bir roblox-signature mantık oluşturur.

Webhook güvenliğini doğrula

Sunucunuzu yükler almak için yapılandırdıktan sonra, uç noktaya gönderilen herhangi bir yükü dinlemeye başlar.Webhook'unuzu yapılandırırken bir sır verirseniz, Roblox, isteğin Roblox'tan geldiğinden emin olmak için her webhook bildirimine bir roblox-signature gönderir.İmza, özel son noktalar için ödeme başlığında ve üçüncü taraf sunucular için ayak izinde bulunur.

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

Webhook için bir sır tutmadıysanız, imza yalnızca bildirimin gönderildiği tarihi içerir:

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

Bir imzayı doğrulamak için:

Zaman damgası ve imza değerlerini çıkarın.Sırlarla webhookler için tüm imzalar, önceliklerden sonra bu iki değerle aynı biçime sahip bir CSV dizesi ile paylaşır:
- t : Bildirimin gönderildiği tarih ve saat.
- v1 : Yaratıcı Panosu yapılandırması tarafından sağlanan gizli değer kullanılarak üretilen imza değeri.
Yeniden yaratmak için roblox-signature üzerine bağlayarak temel dizeyi yeniden oluşturun:
1. Süreç zamanı bir dize olarak.
2. Dönem karakteri . .
3. İstek gövdesinin JSON dizesi.
Yapılandırma sırasında anahtar olarak tanımladığınız gizli ve 2. adımda oluşturduğunuz mesaj olarak temel dize kullanarak SHA256 hash işleviyle bir hash tabanlı mesaj doğrulama kodu (HMAC) hesaplayın.Beklenen imzayı almak için sonucu Base64 formatına dönüştürün.
Çıkarılan imza değerini beklenen imzaya karşılaştırın. Eğer imzayı doğru oluşturduysanız, değer aynı olmalıdır.
(Opsiyonel) Yeniden oynatma saldırılarını önlemek için, saldırganlar yetkisiz erişim kazanmak veya kötü niyetli eylemler gerçekleştirmek için verileri alıp yeniden gönderen bir tür siber saldırı, çıkarılan zamana değer karşılaştırmak ve makul bir süre sınırı içinde olduğundan emin olmak için güncel zamana göre yapılması gerekir.Örneğin, 10 dakikalık bir pencere genellikle iyi bir makul süre sınırıdır.

Yük şeması

Webhook'un hedef etkinliği tetiklendiğinde, ödülün içindeki olayla ilgili bilgiler de dahil olmak üzere webhook URL'sine bir istek gönderir.Tüm isteklerin yükleri sabit ve değişken alanlardan oluşan aynı şemayı paylaşır.Bu, yüklemede aktarılan verilerin yapılandırılmış ve tutarlı olmasını sağlar, böylece alıcı uygulama verileri işlemek ve kullanmak daha kolay hale gelir. sabit yük planı alanları , mevcut alanlarla tüm webhook istekleri arasında tutarlılığı korumaya yardımcı olabilir:

NotificationId (dize): Her gönderilen bildirim için benzersiz bir tanımlayıcı. Aynı NotificationId iki kez alınırsa, yinelenen olarak kabul edilir.
EventType (dize): Bildirimin tetiklendiği olay türünü gösterir.
EventTime (dize): Etkinliğin tetiklendiği tarih ve saat.

The değişken yük planı alanları webhook'ların çeşitli türde olayları barındırmasına esneklik sağlar, bunlar şunları içerir:

EventPayload (objekt): Webhook'u tetikleyen EventType ile ilgili bilgileri içerirEventPayload şemasının yapısı, olay türüne bağlı olarak değişir.

Aşağıdaki örnek, Silme İsteği etkinliğinin yük planını gösterir:

Silme isteği için örnek şema
{
   "NotificationId": "string",
   "EventType": "RightToErasureRequest",
   "EventTime": "2023-12-30T16:24:24.2118874Z",
   "EventPayload": {
      "UserId": 1,
      "GameIds": [
         1234, 2345
      ]
   }
}

Bildirimleri ele alma

Kullanıcılarınızın Kullanıcı Kimlikleri gibi herhangi bir Kişisel Tanımlayıcı Bilgi (PII) saklarsanız, bir kullanıcı böyle bir talepte bulunduğunda bu bilgileri silmelisiniz, GDPR'nin silme hakkına uyumluluk gereksinimlerine uymak için.Webhook bildirimlerini işlemek ve veri silmeyi otomatikleştirmeye yardımcı olmak için bir bot oluşturabilirsiniz, PII'yi bir veri depolamasında saklıyorsanız.Silme İsteği Deletion'u Otomatikleştirme Örneği için Guilded veya Discord'da çalışan bir botun Veri depoları için Açık Bulut API'yi kullanarak PII verilerini otomatikleştirme çözümü olarak silmesi üzerine bir örnek görün.Bu örnek, abonelik olayları gibi diğer bildirimlerin ele alınması için uyarlanabilir.

Üçüncü taraf bir aracı yerine webhook sunucunuz olarak özel bir sonuç noktası kullandığınızda, verileri webhook yükünden silmeye çıkarabilir ve kendi otomasyon çözümünüzü inşa edebilirsiniz.Aşağıdaki kod örneği, zaman damgasını doğrulayarak yeniden oynatma saldırılarına karşı önleme örneğidir ve istek Roblox'tan geliyor:

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

Bu sayfadakiler