Webhook bildirimleri

Oyununuzdaki tüm olayları ve kullanıcı taleplerini manuel olarak izlemek yerine, HTTP isteklerini alabilen üçüncü taraf bir mesajlaşma aracı veya özel bir uç noktada gerçek zamanlı bildirimler almak için web kancaları ayarlayabilirsiniz. Bu, bildirimleri yönetme iş akışınızı otomatikleştirmenize yardımcı olur ve bildirimlerle ilgili manuel çabayı azaltır.

Webhook iş akışı

Web kancaları, Roblox ve bir üçüncü taraf mesajlaşma aracı gibi iki farklı uygulama veya hizmet arasında gerçek zamanlı bildirimler veya veriler gönderir. Geleneksel API'lerin aksine, bir istemci uygulaması kurup sunucuya veri almak için istek göndermeniz gerekmez; web kancaları, bir olay meydana geldiğinde verileri istemci uç noktanıza gönderir. Bu, ekibinizle işbirliği yapmak için kullandığınız üçüncü taraf uygulamalarla Roblox arasında iş akışlarını otomatikleştirmek için yararlıdır, çünkü gerçek zamanlı veri paylaşımı ve işleme sağlar.

Bir web kancası ayarladıktan sonra, hedef bir olay meydana geldiğinde, Roblox sağladığınız webhook URL'sine bir istek gönderir. Webhook URL'si, isteği alıcı uygulamanıza veya özel uç noktanıza yönlendirir; bu, webhook yükünde yer alan verilere dayanarak işlem yapabilir. Bu, RTBF uyumluluğu için verileri silmeyi, kullanıcıya bir onay göndermeyi veya başka bir olayı tetiklemeyi içerebilir.

Desteklenen tetikleyiciler

Roblox şu anda aşağıdaki olay tetikleyicilerini desteklemektedir.

Abonelik

• Abonelik Yenilendi - Bir kullanıcı bir aboneliğe yeniden abone olduğunda, abonelik ve abone bilgilerini içeren bir mesaj gönderilir.
• Abonelik Yenilendi - Bir kullanıcı bir aboneliği yenilediğinde, abonelik ve abone bilgilerini içeren bir mesaj gönderilir.
• Abonelik İade Edildi - Bir kullanıcı aboneliği için bir iade aldığında, abonelik ve abone bilgilerini içeren bir mesaj gönderilir.
• Abonelik Satın Alındı - Bir kullanıcı bir abonelik satın aldığında, abonelik ve abone bilgilerini içeren bir mesaj gönderilir.
• Abonelik İptal Edildi - Bir kullanıcı bir aboneliği iptal ettiğinde, abonelik ve abone bilgilerini içeren bir mesaj gönderilir; ayrıca iptal için verilen neden de belirtilir.

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

Uyumluluk

• Silme Hakkı / Silme Talebi - Bir kullanıcı, geçerli küresel veri koruma ve gizlilik düzenlemeleri uyarınca kişisel bilgilerinin kalıcı olarak silinmesi hakkını kullandığında. Daha fazla bilgi için RTBF ve Yaratıcılar sayfasına bakabilirsiniz.

Ticaret

• Ticaret Ürün Siparişi İade Edildi - Bir kullanıcı ticaret ürün siparişi için bir iade aldığında veya sipariş iptal edildiğinde.
• Ticaret Ürün Siparişi Ödendi - Bir kullanıcı ticaret ürün siparişi için ödeme yaptığında. Lütfen, tekrar eden webhook olaylarının mümkün olduğunu unutmayın, bu nedenle olayları benzersiz ticaret sipariş kimliği kullanarak tekrar etmeyecek şekilde işleyin.

Webhook'ları Yaratıcı Kontrol Panelinde Yapılandırma

Webhook'lar aracılığıyla bildirim almak için, bildirimleri tetiklemek için belirli olaylara abone olan bir webhook yapılandırmanız gerekir. Grup sahipliğindeki oyunlar için yalnızca grup sahipleri webhook bildirimlerini yapılandırabilir ve alabilir.

Bir webhook ayarlamak için:

1. Yaratıcı Merkezi üzerinde deneyiminizi seçin.

2. Yapılandır altında Webhook'lar seçeneğini belirleyin ve Webhook Ekle butonuna tıklayın.

   Webhook URL'si sağlayıcınızdan gelir. Örneğin, bir Slack URL'si muhtemelen şöyle görünür:

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

3. Webhook URL'nizi ve bir ad girin.

4. OPSİYONEL

   Bildirimlerin Roblox'tan geldiğini doğrulamaya yardımcı olan bir gizli anahtar ekleyin. Daha fazla bilgi için Webhook güvenliğini doğrulama sayfasına bakın.

5. Bildirim almak istediğiniz desteklenen tetikleyiciler listesinden bir veya daha fazla seçenek seçin.

6. OPSİYONEL

   Hizmetinizin bir örnek isteği alıp almadığını kontrol etmek için Test Yanıtı butonunu kullanın.

7. Değişiklikleri Kaydet butonuna tıklayın.

Webhook URL'lerini Ayarlama

Webhook URL'niz olarak özel bir HTTP hizmet uç noktası ayarlayabilirsiniz, sağladığınız uç nokta aşağıdaki gereksinimleri karşılamalıdır:

• İstekleri işlemek için kamuya açık erişilebilir olmalıdır.
• POST isteklerini işleyebilmelidir.
• İsteğe 5 saniye içinde 2XX yanıtı verebilmelidir.
• HTTPS isteklerini işleyebilmelidir.

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

• POST mesajının gövdesinden bildirimle ilgili gerekli ayrıntıları çıkarmak.
• POST mesajının gövdesini, bildirimle ilgili genel ayrıntılar ve olay türüne özgü ayrıntılarla okumak.

İşlemeniz gereken POST isteklerinin şeması hakkında daha fazla bilgi için Yük Şeması sayfasına bakın.

Teslimat hatası tekrar deneme politikası

Bir webhook bildirimi, belirttiğiniz URL'ye ulaşamadığında, Roblox, yapılandırılmış URL'ye mesajı 5 kez göndermeyi dener. Eğer bildirim 5 denemeden sonra hala ulaşılamıyorsa, Roblox, bildirimi göndermeyi durdurur ve URL'nin artık geçerli olmadığını varsayar. Bu durumda, webhook yapılandırmanızı, ulaşılabilir ve bildirim alabilen yeni bir URL ile güncellemeniz gerekir. Webhook URL'nizin başarılı bir şekilde bildirim alıp almadığını kontrol etmek için Webhook'ları Test Et sayfasına bakın.

Üçüncü taraf gereksinimleri

Üçüncü taraf araçlar genellikle webhook'lar için kendi gereksinimlerine sahiptir; bu gereksinimlere webhook URL'nizi ayarlarken uymanız gerekir. Bu gereksinimleri, hedef aracın destek veya dokümantasyon sitesinde "webhook" anahtar kelimesini arayarak bulabilirsiniz. Desteklenen üçüncü taraf araçlar için aşağıdakilere bakın:

• Discord Yardım Merkezi
• Slack API Referansı

Webhook'ları Test Et

Yapılandırdığınız webhook'un Yaratıcı Kontrol Paneli üzerinde başarılı bir şekilde bildirim alıp almadığını test edebilirsiniz:

1. Webhook'lar yapılandırma sayfasına gidin.
2. Test etmek istediğiniz webhook'u yapılandırılmış webhook'lar listesinden seçin.
3. Hedef webhook'un yanındaki kalem simgesine tıklayın.
4. Test Yanıtı butonuna tıklayın.

Sistem, bildirim tetikleyen kullanıcının Kullanıcı Kimliği'ni içeren bir SampleNotification olayı gönderir; bu, aşağıda gösterildiği gibidir:

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

Webhook'unuzu bir üçüncü taraf hizmetle entegre ediyorsanız, hizmetin webhook'unuzdan bildirimleri başarılı bir şekilde alıp almadığını doğrulamak için üçüncü taraf URL'sini kullanarak test edebilirsiniz. Webhook'u yapılandırırken bir gizli anahtar sağlarsanız, roblox-signature'ı test etmek için kullanabileceğiniz bir roblox-signature da oluşturur.

Webhook güvenliğini doğrulama

Sunucunuzu yükleri almak için yapılandırdıktan sonra, uç noktaya gönderilen herhangi bir yük için dinlemeye başlar. Webhook'unuzu yapılandırırken bir gizli anahtar ayarladıysanız, Roblox, her webhook bildiriminde isteğin gerçekten Roblox'tan geldiğini doğrulamak için bir roblox-signature gönderir. İmza, özel uç noktalar için yük başlığında ve üçüncü taraf sunucular için alt kısımda bulunur.

t=<timestamp>,v1=<signature>

Webhook'unuz için bir gizli anahtar ayarlamadıysanız, imza yalnızca bildirimin gönderildiği zamanın zaman damgasını içerir:

t=<timestamp>

Bir imzayı doğrulamak için:

1. Zaman damgası ve imza değerlerini çıkarın. Gizli anahtar içeren webhook'lar için tüm imzalar, bu iki değeri takip eden bir CSV dizesi formatını paylaşır:

   • t: Bildirimin gönderildiği zaman damgası.
   • v1: Yaratıcı Kontrol Paneli yapılandırmasında sağlanan gizli anahtarla oluşturulan imza değeri.

2. roblox-signature'ın temel dizesini yeniden oluşturmak için birleştirin:

   1. Zaman damgasını bir dize olarak.
   2. Nokta karakteri ..
   3. İstek gövdesinin JSON dizesi.

3. Belirttiğiniz gizli anahtarı anahtar olarak ve adım 2'de oluşturduğunuz temel dizeyi mesaj olarak kullanarak SHA256 hash fonksiyonu ile bir hash tabanlı mesaj kimlik doğrulama kodu (HMAC) hesaplayın. Sonucu Base64 formatına dönüştürerek beklenen imzayı elde edin.

4. Çıkarılan imza değerini beklenen imza ile karşılaştırın. İmzanızı doğru bir şekilde oluşturduysanız, değer aynı olmalıdır.

5. OPSİYONEL

   Yeniden oynatma saldırılarını önlemek için, saldırganların yetkisiz erişim sağlamak veya kötü niyetli eylemler gerçekleştirmek için verileri kesip yeniden göndermesi türündeki bir siber saldırı türü, çıkarılan zaman damgası değerini mevcut zaman damgası ile karşılaştırmak ve makul bir zaman sınırı içinde kalmasını sağlamak faydalıdır. Örneğin, 10 dakikalık bir pencere genellikle iyi bir makul zaman sınırıdır.

Yük şeması

Webhook'unuzun hedef olayı tetiklendiğinde, webhook URL'nize bir istek gönderir ve yükte olay hakkında bilgi içerir. Tüm istek yükleri, sabit ve değişken alanlardan oluşan aynı şemayı paylaşır. Bu, yükte iletilen verilerin yapılandırılmış ve tutarlı olmasını sağlar, böylece alıcı uygulamanın verileri işlemesi ve kullanması daha kolay hale gelir.

Sabit yük şeması alanları, tüm webhook istekleri arasında tutarlılığı korumaya yardımcı olabilir ve aşağıdaki alanlar mevcuttur:

1. NotificationId (dize): Gönderilen her bildirim için benzersiz bir tanımlayıcı. Aynı NotificationId iki kez alındığında, bu bir kopya olarak kabul edilir.
2. EventType (dize): Bildirimin tetiklendiği olayın türünü belirtir.
3. EventTime (dize): Olayın tetiklendiği zaman damgası.

Değişken yük şeması alanları, webhook'ların çeşitli olay türlerini karşılaması için esneklik sağlar ve şunları içerir:

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

Aşağıdaki örnek, Silme Hakkı talebi olayı için yük şemasını göstermektedir:

{
   "NotificationId": "string",
   "EventType": "RightToErasureRequest",
   "EventTime": "2023-12-30T16:24:24.2118874Z",
   "EventPayload": {
      "UserId": 1,
      "GameIds": [
         1234, 2345
      ]
   }
}

Bildirimleri İşleme

Kullanıcılarınızın Kişisel Olarak Tanımlanabilir Bilgilerini (PII), örneğin Kullanıcı Kimliklerini saklıyorsanız, talebi yasal yükümlülükleriniz açısından değerlendirmeniz gerekir. Daha fazla bilgi için RTBF ve Yaratıcılar sayfasına bakabilirsiniz. Webhook bildirimlerini işlemek ve PII'yi bir veri deposunda saklıyorsanız veri silme işlemini otomatikleştirmek için bir bot oluşturabilirsiniz. Silme Hakkı Talepleri Silme Otomasyonu sayfasında, PII verilerini silmek için Açık Bulut API'sini kullanan Discord içinde bir bot oluşturma örneği bulunmaktadır. Bu örnek, abonelik olayları gibi diğer bildirimleri işlemek için de uyarlanabilir.

Üçüncü taraf bir araç yerine özel bir uç nokta olarak webhook sunucusu kullanıyorsanız, yükten silinecek verileri çıkarabilir ve kendi otomasyon çözümünüzü oluşturabilirsiniz. Aşağıdaki kod örneği, zaman damgasını doğrulayarak ve isteğin Roblox'tan geldiğini kontrol ederek yeniden oynatma saldırılarına karşı koruma sağlayan bir sunucunun örneğidir:

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

const secret = '<your_secret>' // Bu bir ortam değişkeni olarak ayarlanabilir

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

app.all('/*', function (req, res) {
   console.log('Yeni istek alındı');

   // Başlıktan zaman damgası ve imzayı çıkar
   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);

   // Yeniden oynatma saldırılarını önlemek için isteğin 300 saniyelik bir pencerede geldiğinden emin olun
   const requestTimestampMs = timestamp * 1000;
   const windowTimeMs = 300 * 1000;
   const oldestTimestampAllowed = Date.now() - windowTimeMs;

   if (requestTimestampMs < oldestTimestampAllowed) {
      return res.status(403).send('Süresi Dolmuş İstek');
   }

   // İmza doğrulama
   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('Yetkisiz İstek');
   }

   // Yükü işleme mantığınız
   const payloadBody = req.body;
   const eventType = payloadBody['EventType'];

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

      console.log(`Yük verisi: Kullanıcı Kimliği=${userId} ve Oyun Kimlikleri=${gameIds}`);
      // Eğer PII'yi veri depolarında saklıyorsanız, Kullanıcı Kimliği ve Oyun Kimliklerini kullanarak bilgileri veri depolarından silin.
   }

   return res.json({ message: 'Mesaj başarıyla işlendi' });
});

app.listen(8080, function () {
   console.log('Sunucu başlatıldı');
});