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'lerin aksine, bir sunucuya veri göndermek için bir istemci uygulaması kurmanızı gerektirenlerin aksine, 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 bildirimler için aşağıdaki olay tetikleyicilerini destekliyor:

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 Satın Alındı - Bir kullanıcı abonelik satın aldığında, 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.
Abonman yenilendi - Bir kullanıcı bir aboneliği yenilediğinde, abonelik ve abone içeren bir mesaj gönderilir.
Abonelik yeniden abone edildi - Bir kullanıcı bir aboneliğe yeniden abone olduğunda, abonelik ve abone içeren bir mesaj gönderilir.
"Unutulma hakkı" Genel Veri Koruma Yönetmeliği'nde veri silme istekleri ( GDPR ).

Abonelik etkinlikleri ve alanları hakkında daha fazla bilgi için Bulut API Aboneliği referansına bakın.

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 ve üçüncü taraf entitelerden gelen webhook URL'lerini kabul etmek istediğiniz URL'yi belirtinGereksinimlerle 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 — Alarm almak istediğiniz olayların desteklenen tetikleyiciler listesinden bir veya daha fazla seçenek seçin desteklenen tetikleyiciler listesi için bildirim almak için.
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 talepaldığı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, takip edilenbakı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 sonra bir bildirim gönderir SampleNotification yaz, ki bunun içinde bildirimi tetikleyen kullanıcının Kullanıcı Kimliği dahil edilir, aşağıdaki örnek şeması gösterdiği gibi:

Örnek Bildirim Semaforması
Body: {
  "NotificationId": "string",
  "EventType": "SampleNotification",
  "EventTime": "2023-12-30T16:24:24.2118874Z", // Tür: ISO 8601 Zaman damgası
  "EventPayload": {
    "UserId": 1 // Tür: Uzun
  }
}

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 belirlediyseniz, Roblox, veri güvenliğinizi korumaya yardımcı olmak için her webhook bildirimi ile birlikte bir roblox-signature gönderir.Bu şekilde, bildirimin Roblox'tan olduğunu doğrulamak ve sunucunuzun sadece Roblox'tan gelen istekleri almasını sınırlamak için kullanabilirsiniz.İmza, özel son noktalar için ödeme başlığında ve üçüncü taraf sunucular için ayak izinde bulunur.

Signature Format with Secret for Custom Endpoints
"roblox-signature": "t=<timestamp>,v1=<signature>"

Webhook'unuz için bir sır bulunmuyorsa, aldığınız imza sadece bildirim gönderildiğinde zaman damgası değerini içerir:

Signature Format without Secret for Custom Endpoints
"roblox-signature": "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 : Bildirim gönderildiğinde tarih değeri.
- v1 : Yaratıcı Panosu yapılandırması tarafından sağlanan gizli değer kullanılarak üretilen imza değeri.Bu iki değeri bir ayrıcıya dayalı olarak dizeye ayıran split() fonksiyonu kullanarak çıkarabilirsiniz, bu durumda , karakteri.
Yeniden yaratmak için roblox-signature üzerine bağlayarak temel dizeyi yeniden oluşturun:
1. Süreç zamanı bir diziolarak.
2. Dönem karakteri . .
3. İstek gövdesinin JSON dizesi.
Yapılandırma sırasında tanımladığınız anahtar ve 2. adımda oluşturduğunuz temel dize olarak tanımladığınız mesaj için SHA256 hash işlevini kullanarak bir Hash tabanlı mesaj doğrulama kodunu hesaplayın (HMAC).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 , string : Her gönderilen bildirim için benzersiz bir tanımlayıcı. Aynı NotificationId iki kez alınırsa, yinelenen olarak kabul edilir.
EventType , string : Bir dize, bildirimin tetiklendiği olay türünü temsil eder.
EventTime , timestamp : Etkinliğin tetiklendiğini gösteren yaklaşık bir zaman damgası

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 , object : 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 şemasını gösterir:

Silme İsteğine İlişkin Örnek Şema
Body:{

   "NotificationId": "string",

   "EventType": "RightToErasureRequest",

   "EventTime": "2023-12-30T16:24:24.2118874Z",

   "EventPayload": {

      "UserId": 1, // Tür: Uzun

      "GameIds": [ // Tür: Uzunlukların bir dizi

         1234, 2345

      ]

   }

}

Bildirimleri ele alma

Kullanıcılarınızın Kullanıcı Kimlikleri gibi herhangi bir Kişisel Tanımlayıcı Bilgi (Kişisel Tanıtıcı Bilgiler) 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 mağazasaklı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 bir örnek çözüm sağlar ve isteğin Roblox'tan geldiğini doğrulayarak yeniden oynatma saldırılarına engelleme ekler:

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

Bu sayfadakiler