Notifications de webhook

Au lieu de surveiller manuellement tous les événements dans votre expérience et les demandes des utilisateurs, vous pouvez configurer des webhooks pour recevoir des notifications en temps réel sur un outil de messagerie tiers ou sur votre point final personnalisé qui peut recevoir des demandes HTTP.Cela vous aide à automatiser votre flux de travail de gestion des notifications pour réduire les notifications d'effort manuel.

Actuellement, Roblox prend entièrement en charge les notifications webhook pour Discord, Guilded et Slack.L'utilisation de webhooks avec d'autres outils tiers comporte le risque de ne pas recevoir toutes les notifications.

Flux de travail Webhook

Les webhooks envoient des notifications ou des données en temps réel entre deux applications ou services différents, tels que Roblox et un outil de messagerie tiers.Contrairement aux API traditionnelles, qui nécessitent que vous configuriez une application client pour envoyer des demandes à un serveur pour recevoir des données, les webhooks envoient des données à votre point d'extrémité client dès qu'un événement se produit.Ils sont utiles pour automatiser les workflows entre Roblox et les applications tierces que vous utilisez pour collaborer avec votre équipe, car ils permettent un partage et un traitement de données en temps réel.

Une fois que vous avez configuré un webhook, chaque fois qu'un événement cible se produit, Roblox envoie une demande à l'URL du webhook que vous fournir.L'URL du webhook redirige ensuite la demande vers votre application de réception ou votre point final personnalisé, qui peut agir en fonction des données incluses dans le paquet webhook.Cela pourrait inclure l'effacement des données pour le RGPD, l'envoi d'une confirmation à l'utilisateur ou le déclenchement d'un autre événement.

Cibles soutenues

Roblox prend actuellement en charge les déclencheurs d'événement suivants pour les notifications :

Abonnement annulé - Lorsqu'un utilisateur annule un abonnement abonnement, un message est envoyé contenant l'abonnement et l'abonné, ainsi que la raison donnée pour l'annulation.
Abonnement acheté - Lorsqu'un utilisateur achète un abonnement, un message est envoyé contenant l'abonnement et l'abonné.
Remboursement d'abonnement - Lorsqu'un utilisateur reçoit un remboursement pour son abonnement, un message est envoyé contenant l'abonnement et l'abonné.
Abonnement renouvelé - Lorsqu'un utilisateur renouvelle un abonnement, un message est envoyé contenant l'abonnement et l'abonné.
Abonnement réabonné - Lorsqu'un utilisateur réabonne à un abonnement, un message est envoyé contenant l'abonnement et l'abonné.
« Droit d'être oublié » demandes de suppression de données en vertu du règlement général sur la protection des données ( RGPD ).

Pour plus d'informations sur les événements d'abonnement et leurs champs, voir la référence Abonnement à l'API du cloud.

Configurer les webhooks sur le tableau de bord du créateur

Pour recevoir des notifications via des webhooks, vous devez configurer un webhook qui s'abonne à certains événements pour déclencher des notifications.Pour les expériences appartenant à un groupe, seuls les propriétaires de groupe peuvent configurer et recevoir des notifications Webhook.

Si vous configurez des webhooks et traitez des données personnelles, assurez-vous qu'ils respectent le règlement général sur la protection des données (RGPD).

Pour configurer un webhook :

Accédez à la section Webhooks du tableau de bord du créateur.
Cliquez sur le bouton Ajouter Webhook .
Complétez les champs de configuration :
1. URL du Webhook — Spécifiez l'URL où vous souhaitez recevoir des notifications et accepter les URL de Webhook entrantes de la part d'entités tierces.Pour plus d'informations sur les exigences, voir Configurer les URLs de webhook.
2. Nom — Utilisez un nom personnalisé pour différencier votre configuration des autres. Par défaut, la valeur est la même que l'URL du Webhook.
3. Secret (facultatif) — Fournissez un secret si vous voulez vérifier que les notifications que vous recevez proviennent de Roblox.Pour plus d'informations, voir Vérifier la sécurité du webhook.
4. déclencheurs — Choisissez une ou plusieurs options de la liste des déclencheurs pris en charge des événements pour lesquels vous souhaitez recevoir des notifications.
Cliquez sur le bouton Enregistrer les modifications .

Actuellement, vous pouvez configurer jusqu'à 5 webhooks au total.

Configurer les URLs de webhook

Vous pouvez configurer un point d'extrémité de service HTTP personnalisé comme URL de webhook, à condition qu'il remplisse les exigences suivantes :

Il doit être accessible publiquement pour gérer les demandes.
Il peut gérer les demandes POST.
Il peut répondre à la demande avec une réponse 2XX dans les 5 secondes.
Il peut gérer les demandes HTTPS.

Lorsque votre point final reçoit une demande POST, il doit être en mesure de :

Extrayez les détails requis au sujet de la notification du corps du message POST.
Lisez le corps du message POST avec les détails génériques sur la notification et les détails spécifiques liés au type d'événement sur la notification.

Pour plus d'informations sur le schéma des demandes POST à contrôleur, voir le schéma de chargement.

politiquede réessai de l'échec de livraison

Lorsqu'une notification Webhook ne parvient pas à atteindre l'URL spécifiée en raison d'erreurs telles que l'indisponibilité de l'extrémité, Roblox réessaie d'envoyer le message à l'URL configurée 5 fois en utilisant une taille de fenêtre fixe.Si la notification n'est toujours pas livrée après 5 tentatives, Roblox arrête d'essayer d'envoyer la notification et suppose que l'URL n'est plus valide.Dans cette situation, vous devez mettre à jour votre configuration de webhook avec une nouvelle URL qui soit accessible et capable de recevoir des notifications.Pour résoudre les problèmes et confirmer que votre URL de webhook peut recevoir avec succès des notifications, voir tester les webhooks.

Exigences de tiers

Les outils tiers ont généralement leurs propres exigences pour les webhooks que vous devez suivre lors de la configuration de votre URL de webhook.Vous pouvez trouver ces exigences en recherchant le mot-clé « webhook » sur le site de support ou de documentation du outil cible.Pour les trois outils tiers pris en charge, voir ce qui suit :

Tester les webhooks

Vous pouvez tester si le webhook que vous avez configuré peut recevoir avec succès des notifications sur le tableau de bord du créateur :

Accédez à la page de configuration des Webhooks.
Sélectionnez le webhook que vous voulez tester dans la liste des webhooks configurés.
Cliquez sur l'icône de crayon à côté du webhook cible.
Cliquez sur le bouton Réponse de test .

Le système envoie ensuite une notification du taper, qui inclut l'ID utilisateur de l'utilisateur qui déclenche la notification, comme le montre le schéma d'exemple suivant :

Schéma de notification d'échantillon
Body: {
  "NotificationId": "string",
  "EventType": "SampleNotification",
  "EventTime": "2023-12-30T16:24:24.2118874Z", // Type : Timbre de l'ISO 8601
  "EventPayload": {
    "UserId": 1 // Type : Long
  }
}

Si vous intégrez votre webhook à un service tiers, vous pouvez le tester en utilisant l'URL du tiers pour confirmer que le service peut recevoir avec succès des notifications de votre webhook.Si vous fournissez un secret lors de la configuration du webhook, il génère également un roblox-signature que vous pouvez utiliser pour tester la logique roblox-signature.

Vérifier la sécurité du webhook

Une fois que vous avez configuré votre serveur pour recevoir des charges utiles, il commence à écouter toute charge envoyée à l'extrémité.Si vous définissez un secret lors de la configuration de votre webhook, Roblox envoie un roblox-signature avec chaque notification de webhook pour aider à protéger la sécurité de vos données.De cette façon, vous pouvez utiliser le pour vérifier que la notification provient de Roblox et limiter votre serveur à recevoir uniquement des demandes provenant de Roblox.La signature se trouve dans l'en-tête de chargement pour les points de fin personnalisés et dans le pied de page pour les serveurs tiers.

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

Si vous n'avez pas de secret pour votre webhook, la signature que vous recevez ne contient que la valeur de l'heure d'envoi de la notification :

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

Pour vérifier une signature :

Extrayez la valeur de l'heure et la valeur de la signature.Toutes les signatures pour les webhooks avec des secrets partagent le même format qu'une chaîne CSV avec ces deux valeurs suivies des préfixes :
- t : La valeur de l'heure d'envoi de la notification lorsque celle-ci est envoyée.
- v1 : La valeur de signature générée en utilisant la valeur secrète fournie par la configuration du tableau de bord du créateur.Vous pouvez extraire ces deux valeurs en utilisant la fonction split(), qui sépare la chaîne en fonction d'un séparateur, dans ce cas, le caractère ,.
Recréer la chaîne de base de roblox-signature en concaténant :
1. L'horodatage en tant que chaîne.
2. Le caractère de période ..
3. La chaîne JSON du corps de la demande.
Calculer un code d'authentification de message basé sur le hachage (HMAC) avec la fonction de hachage SHA256 en utilisant le mot de passe que vous avez défini lors de la configuration comme clé et la chaîne de base que vous avez générée à travers l'étape 2 comme message.Convertissez la résultante au format Base64 pour obtenir la signature attendue.
Comparez la valeur de signature extraite à la signature attendue. Si vous avez généré la signature correctement, la valeur devrait être la même.
(Facultatif) Pour empêcher les attaques de relecture, un type d'attaque cybernétique où les attaquants interceptent et renvoient des données pour obtenir un accès non autorisé ou effectuer des actions malveillantes, il est utile de comparer la valeur de l'horodatage extrait avec la date d'horodatage actuelle et de s'assurer qu'elle tombe dans une limite de temps raisonnable.Par exemple, une fenêtre de 10 minutes est généralement une bonne limite raisonnable.

Schéma de chargement

Lorsque l'événement cible de votre webhook est déclenché, il envoie une demande à l'URL de votre webhook, y compris des informations sur l'événement dans le corps du message.Tous les paiements de requêtes partagent le même schéma qui se compose de champs fixes et variables.Cela garantit que les données transmises dans le corps du message sont structurées et cohérentes, ce qui facilite le traitement et l'utilisation des données par l'application de réception.

Les champs de schéma de chargement fixe peuvent aider à maintenir la cohérence sur toutes les demandes Webhook, avec les champs suivants disponibles :

NotificationId , string : Un identifiant unique pour chaque notification envoyée. Si le même NotificationId est reçu deux fois, il est considéré comme dupliqué.
EventType , string : Une chaîne représente le type d'événement pour lequel la notification a été déclenchée.
EventTime , timestamp : Un timestamp approximatif indiquant quand l'événement a été déclenché.

Le champ de schéma de paiement variable fournit une flexibilité pour les webhooks afin d'accueillir différents types d'événements, qui comprennent :

EventPayload , object : Contient des informations spécifiques à la EventType qui a déclenché le webhook.La structure du schéma EventPayload varie en fonction du type d'événement.

L'exemple suivant montre le schéma de chargement de l'événement Demande de suppression à droite :

Exemple de schéma pour la demande de suppression à droite
Body:{

   "NotificationId": "string",

   "EventType": "RightToErasureRequest",

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

   "EventPayload": {

      "UserId": 1, // Type : Long

      "GameIds": [ // Type : Un tableau de Longs

         1234, 2345

      ]

   }

}

Gérer les notifications

Si vous stockez toute information personnellement identifiable (IPI) de vos utilisateurs, telle que leurs identifiants d'utilisateur, vous devez supprimer ces informations lorsqu'un utilisateur soumet une telle demande pour respecter les exigences de conformité au RGPD droit à l'effacement.Vous pouvez créer un bot pour gérer les notifications Webhook et aider à automatiser la suppression des données, à condition que vous stockiez des PII dans un boutiquede données.Voir Automatisation des demandes de suppression des droits à l'effacement pour un exemple sur la façon de créer un bot dans Guilded ou Discord qui utilise la Open Cloud API pour les magasins de données pour supprimer les données PII en tant que solution d'automatisation.Cet exemple peut être adapté pour gérer d'autres notifications, telles que les événements d'abonnement.

Si vous utilisez un point final personnalisé comme serveur de webhook au lieu d'un outil tiers, vous pouvez extraire les données soumises à suppression du payload webhook et construire votre propre solution d'automatisation.L'exemple de code suivant fournit une solution d'exemple et ajoute une prévention aux attaques de relecture en vérifiant que la demande provient de 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')
})

Sur cette page