Webhook bildirimleri

Oyununuza gelen tüm olayları ve kullanıcı taleplerini manuel olarak takip etmek yerine, HTTP istekleri alabilen özel bir uç noktaya veya üçüncü taraf bir mesajlaşma aracına gerçek zamanlı bildirimler almak için webhook'lar kurabilirsiniz. Bu, bildirimleri yönetme iş akışınızı otomatikleştirmenize yardımcı olur ve manuel çaba gereksinimini azaltır.

Webhook iş akışı

Webhook'lar, Roblox ve üçüncü taraf mesajlaşma aracı gibi iki farklı uygulama veya hizmet arasında gerçek zamanlı bildirimler veya veriler gönderir. Veriler almak için bir istemci uygulaması ayarlamanızı gerektiren geleneksel API'lerin aksine, webhook'lar bir olay meydana geldiğinde verileri istemci uç noktanıza gönderir. Ekiplerinizle işbirliği yapmak için kullandığınız üçüncü taraf uygulamalar ile Roblox arasındaki iş akışlarını otomatikleştirmek için faydalıdırlar; çünkü gerçek zamanlı veri paylaşımı ve işleme sağlarlar.

Bir webhook kurduğunuzda, 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 harekete geçebilir. Bu, RTBF uyumluluğu için verilerin silinmesini, 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 aboneliği yapan kişiyi içeren bir mesaj gönderilir.
• Abonelik Uzatıldı - Bir kullanıcı bir aboneliği yenilediğinde, abonelik ve aboneliği yapan kişiyi içeren bir mesaj gönderilir.
• Abonelik İade Edildi - Bir kullanıcı aboneliği için iade aldığında, abonelik ve aboneliği yapan kişiyi içeren bir mesaj gönderilir.
• Abonelik Satın Alındı - Bir kullanıcı bir abonelik satın aldığında, abonelik ve aboneliği yapan kişiyi içeren bir mesaj gönderilir.
• Abonelik İptal Edildi - Bir kullanıcı bir aboneliği iptal ettiğinde, abonelik ve aboneliği yapan kişiyi, ayrıca iptal için verilen sebebi içeren bir mesaj gönderilir.

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 kapsamında kişisel bilgilerinin kalıcı olarak silinmesini sağladığında. Daha fazla bilgi için RTBF ve Yaratıcılar kısmına bakabilirsiniz.

Ticaret

• Ticari Ürün Siparişi İade Edildi - Bir kullanıcı, ticari ürün siparişi için bir iade aldığında veya sipariş iptal edildiğinde.
• Ticari Ürün Siparişi Ödendi - Bir kullanıcı, ticari ürün siparişi için ödeme yaptığında. Lütfen, tekrar eden webhook olaylarının mümkün olduğunu unutmayın; dolayısıyla, olayları benzersiz ticaret sipariş ID'si kullanarak tekrar etmeye çalışmalısınız.

Webhook'ları Creator Dashboard'da 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ğine sahip oyunlar için, yalnızca grup sahipleri webhook bildirimlerini yapılandırabilir ve alabilir.

Bir webhook kurmak için:

1. Creator Hub üzerinde deneyiminizi seçin.

2. Yapılandır altında Webhook'lar'ı seçin ve Webhook Ekle'ye 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. (Opsiyonel) Bildirimlerin Roblox'tan geldiğini güvence altına almak için bir gizli anahtar ekleyin. Daha fazla bilgi için Webhook güvenliğini doğrulayın kısmına bakın.

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

6. (Opsiyonel) Hizmetinizin bir örnek isteği alıp almadığını kontrol etmek için Test Yanıtı düğmesini kullanın.

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

Webhook URL'lerini ayarlama

Webhook URL'niz olarak özel bir HTTP hizmet uç noktası ayarlayabilirsiniz, provided it fulfills the following requirements:

• Talepleri karşılamak için herkese açık bir şekilde erişilebilir olmalıdır.
• POST isteklerini karşılayabilmelidir.
• 5 saniye içinde 2XX yanıtı verebilmelidir.
• HTTPS isteklerini karşılayabilmelidir.

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

• POST mesajının gövdesinden bildirim hakkında gereken bilgileri çıkarmalıdır.
• Gövdesi, bildirimle ilgili genel bilgileri ve bildirim türüne özgü bilgileri okuyabilmelidir.

İşlem yapmanız gereken POST isteklerinin şeması hakkında daha fazla bilgi için Yük Şeması kısmına bakın.

İletim hatası tekrar deneme politikası

Webhook bildirimi, belirtilen URL'nize ulaşamadığında, Roblox yapılandırılan URL'ye mesaj göndermeye 5 kez, sabit bir pencere boyutu kullanarak tekrar dener. Eğer 5 denemeden sonra hala bildirim ulaştırılamazsa, Roblox bildirim göndermeyi durdurur ve URL'nin artık geçerli olmadığını varsayar. Bu durumda, bildirimleri alabilen erişilebilir yeni bir URL ile webhook yapılandırmanızı güncellemeniz gerekir. Webhook URL'nizin bildirimleri başarıyla alabileceğini doğrulamak için Webhook'ları Test Et kısmına bakın.

Üçüncü taraf gereksinimleri

Üçüncü taraf araçlar genellikle webhook'lar için kendi gereksinimlerine sahiptirler; bu gereksinimlere webhook URL'nizi kurarken uymalısınız. Bu gereksinimleri hedef aracın destek veya dökümantasyon sitesinde "webhook" anahtar kelimesini arayarak bulabilirsiniz. Desteklenen üçüncü taraf araçlar için aşağıdakilere bakabilirsiniz:

• Discord Yardım Merkezi
• Slack API Referansı

Webhook'ları Test Et

Yapılandırdığınız webhook'un bildirimleri başarılı bir şekilde alıp almadığını Creator Dashboard üzerinde test edebilirsiniz:

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

Sistem, bildirimleri tetikleyen kullanıcı Kullanıcı ID'si'ni içeren ÖrnekBildirim olayını gönderir; bu, burada gösterilmiştir:

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

Webhook'unuzu bir üçüncü taraf hizmetle entegre ediyorsanız, üçüncü taraf URL'sini kullanarak test edebilir ve hizmetin başarılı bir şekilde bildirimleri alıp almadığını doğrulayabilirsiniz. Webhook'u yapılandırırken bir gizli anahtar sağlarsanız, roblox-signature oluşturur; bunu roblox-signature mantığını test etmek için kullanabilirsiniz.

Webhook güvenliğini doğrulama

Sunucunuzu yükleri almak için yapılandırdığınızda, uç noktaya gönderilen her yük için dinlemeye başlar. Webhook'unuzu yapılandırırken bir gizli anahtar belirlediyseniz, Roblox her webhook bildiriminde roblox-signature gönderir, bu da isteğin gerçekten Roblox'tan geldiğini sağlamaktadır. Bu imza, ö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 belirlemediyseniz, imza yalnızca bildirimin gönderildiği zamanı içeren bir zaman damgası içerir:

t=<timestamp>

Bir imzayı doğrulamak için:

1. Zaman damgası ve imza değerlerini çıkartın. Gizli anahtar olan webhook'lar için tüm imzalar, şu iki değeri izleyen bu CSV dizesi biçiminde aynı formatı paylaşır:

   • t: Bildirimin gönderildiği zamanın damgası.
   • v1: Creator Dashboard yapılandırmasında sağlanan gizli anahtar ile oluşturulmuş imza değeri.

2. roblox-signature için temel dizeyi yeniden oluşturmak için aşağıdakileri birleştirin:

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

3. Sağladığınız 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 doğrulama kodu (HMAC) hesaplayın. Sonucu Base64 formatına dönüştürerek beklenen imzayı elde edin.

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

5. (Opsiyonel) Yeniden gönderme saldırılarını önlemek için, saldırganların verileri ele geçirdiği ve yeniden gönderdiği bir tür siber saldırı, zaman damgası değerini mevcut zaman damgası ile karşılaştırmak ve bunun makul bir zaman sınırında olup olmadığını kontrol etmek faydalıdır. Örneğin, 10 dakikalık bir pencere genellikle makul bir zaman sınırıdır.

Yük şeması

Webhook'ınızın hedef olayı tetiklendiğinde, yükle ilgili bilgileri içeren bir isteği webhook URL'nize gönderir. 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ğladığı için, alıcı uygulamanın verileri işlemesini ve kullanmasını daha kolay hale getirir.

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

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

Değişken yük şeması alanları, webhook'ların çeşitli türde olaylara uyum sağlaması için esneklik sağlar ve bunlar dahildir:

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

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

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

Bildirimleri yönetme

Kullanıcılarınızın Kişisel Olarak Tanımlanabilir Bilgilerini (KİŞİSEL VERİ) saklıyorsanız, talebi yasal yükümlülükleriniz ışığında değerlendirmelisiniz. Daha fazla bilgi için RTBF ve Yaratıcılar kısmına bakabilirsiniz. Kişisel verileri bir veri deposunda saklıyorsanız, webhook bildirimlerini yönetmek ve veri silme işlemlerini otomatikleştirmek için bir bot oluşturabilirsiniz. Veri depoları için Açık Bulut API kullanarak, diğer bildirimleri, örneğin abonelik olayları gibi, işlemek için bu örneği uyarlayabilirsiniz.

Webhook sunucunuz olarak bir özel uç nokta kullanıyorsanız, yük ile ilgili silinecek verileri webhook yükünden çıkartabilir 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 belirleyerek yeniden gönderme 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ını ve imzayı çıkart
   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 gönderme saldırılarını önlemek için isteğin 300 saniyelik bir zaman penceresi içinde geldiğini doğrulayın
   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ü yönetmek için lojik
   const payloadBody = req.body;
   const eventType = payloadBody['EventType'];

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

      console.log(`Yük verisi: UserId=${userId} ve GameIds=${gameIds}`);
      // Eğer kişisel verileri veri depolarında saklıyorsanız, UserId ve GameIds 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ı');
});