Notifications par webhook

Au lieu de surveiller manuellement tous les événements de votre jeu 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 votre point de terminaison personnalisé capable de recevoir des requêtes HTTP. Cela vous aide à automatiser votre flux de gestion des notifications pour réduire l'effort manuel lié à la gestion des notifications.

Flux de travail des webhooks

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 cliente pour envoyer des requêtes à un serveur afin de recevoir des données, les webhooks envoient des données à votre point de terminaison client dès qu'un événement se produit. Ils sont utiles pour automatiser les flux de travail entre Roblox et les applications tierces que vous utilisez pour collaborer avec votre équipe, car ils permettent un partage et un traitement des 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 requête à l'URL du webhook que vous fournissez. L'URL du webhook redirige ensuite la requête vers votre application réceptrice ou votre point de terminaison personnalisé, qui peut agir en fonction des données incluses dans la charge utile du webhook. Cela pourrait inclure l'effacement des données pour la conformité au RTBF, l'envoi d'une confirmation à l'utilisateur ou le déclenchement d'un autre événement.

Déclencheurs pris en charge

Roblox prend actuellement en charge les déclencheurs d'événements suivants.

Abonnement

• Abonnement Réabonné - Lorsqu'un utilisateur se réabonne à un 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 Remboursé - Lorsqu'un utilisateur reçoit un remboursement pour son abonnement, un message est envoyé contenant l'abonnement et l'abonné.
• Abonnement Acheté - Lorsqu'un utilisateur achète un abonnement, un message est envoyé contenant l'abonnement et l'abonné.
• Abonnement Annulé - Lorsqu'un utilisateur annule un abonnement, un message est envoyé contenant l'abonnement et l'abonné, ainsi que la raison donnée pour l'annulation.

Pour plus d'informations sur les événements d'abonnement et leurs champs, consultez la référence Abonnement.

Conformité

• Droit à l'Effacement / Demande de Suppression - Lorsqu'un utilisateur exerce son droit de faire supprimer définitivement ses informations personnelles conformément aux réglementations mondiales applicables en matière de protection des données et de vie privée. Plus d'informations peuvent être trouvées dans RTBF et Créateurs.

Commerce

• Commande de Produit Commercial Remboursée - Lorsqu'un utilisateur a reçu un remboursement pour sa commande de produit commercial, ou si la commande a été annulée.
• Commande de Produit Commercial Payée - Lorsqu'un utilisateur a payé pour sa commande de produit commercial. Veuillez noter que des événements de webhook en double sont possibles, vous devez donc dédupliquer les événements en utilisant l'ID de commande commerciale unique.

Configurer des webhooks sur le Tableau de Bord 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 jeux appartenant à un groupe, seuls les propriétaires de groupe peuvent configurer et recevoir des notifications par webhook.

Pour configurer un webhook :

1. Sélectionnez votre expérience sur Creator Hub.

2. Sous Configurer, sélectionnez Webhooks et cliquez sur Ajouter un Webhook.

   L'URL du webhook provient de votre fournisseur. Par exemple, une URL Slack ressemble probablement à ceci :

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

3. Entrez votre URL de webhook et un nom.

4. OPTIONNEL

   Incluez un secret, qui aide à garantir que les notifications que vous recevez proviennent de Roblox. Pour plus d'informations, consultez Vérifier la sécurité du webhook.

5. Choisissez une ou plusieurs options dans la liste des déclencheurs pris en charge pour lesquels vous souhaitez recevoir des notifications.

6. OPTIONNEL

   Utilisez le bouton Tester la Réponse pour vérifier si votre service peut recevoir une requête d'exemple.

7. Cliquez sur Enregistrer les Modifications.

Configurer les URL de webhook

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

• Il doit être accessible publiquement pour traiter les requêtes.
• Il doit pouvoir gérer les requêtes POST.
• Il doit pouvoir répondre à la requête avec une réponse 2XX dans un délai de 5 secondes.
• Il doit pouvoir gérer les requêtes HTTPS.

Lorsque votre point de terminaison reçoit une requête POST, il doit être capable de :

• Extraire les détails requis concernant la notification du corps du message POST.
• Lire 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 requêtes POST à gérer, consultez le Schéma de Charge Utile.

Politique de réessai en cas d'échec de livraison

Lorsqu'une notification par webhook échoue à atteindre votre URL spécifiée en raison d'erreurs telles que l'indisponibilité du point de terminaison, Roblox réessaie d'envoyer le message à l'URL configurée 5 fois en utilisant une taille de fenêtre fixe. Si la notification échoue toujours à être livrée après 5 tentatives, Roblox cesse d'essayer d'envoyer la notification et suppose que l'URL n'est plus valide. Dans ce cas, vous devez mettre à jour votre configuration de webhook avec une nouvelle URL qui est accessible et capable de recevoir des notifications. Pour résoudre les problèmes et confirmer que votre URL de webhook peut recevoir des notifications avec succès, consultez Tester les webhooks.

Exigences des 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 de l'outil cible. Pour les outils tiers pris en charge, consultez les éléments suivants :

• Centre d'Aide Discord
• Référence API Slack

Tester les webhooks

Vous pouvez tester si le webhook que vous avez configuré peut recevoir des notifications avec succès sur le Tableau de Bord Créateur :

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

Le système envoie alors un événement SampleNotification, qui inclut l'ID Utilisateur de l'utilisateur qui a déclenché la notification, comme indiqué ici :

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

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

Vérifier la sécurité du webhook

Après avoir configuré votre serveur pour recevoir des charges utiles, il commence à écouter toute charge utile envoyée à l'endpoint. Si vous avez défini un secret lors de la configuration de votre webhook, Roblox envoie une roblox-signature dans chaque notification de webhook pour garantir que la requête provient réellement de Roblox. La signature se trouve dans l'en-tête de la charge utile pour les points de terminaison personnalisés et dans le pied de page pour les serveurs tiers.

t=<timestamp>,v1=<signature>

Si vous n'avez pas défini de secret pour votre webhook, la signature ne contient que l'horodatage de l'envoi de la notification :

t=<timestamp>

Pour vérifier une signature :

1. Extraire les valeurs d'horodatage et de signature. Toutes les signatures pour les webhooks avec secrets partagent le même format qu'une chaîne CSV avec ces deux valeurs suivies des préfixes :

   • t : L'horodatage de l'envoi de la notification.
   • v1 : La valeur de signature générée à l'aide du secret fourni par la configuration du Tableau de Bord Créateur.

2. Recréer la chaîne de base de roblox-signature en concaténant :

   1. L'horodatage sous forme de chaîne.
   2. Le caractère de point ..
   3. La chaîne JSON du corps de la requête.

3. Calculer un code d'authentification de message basé sur un hachage (HMAC) avec la fonction de hachage SHA256 en utilisant le secret que vous avez défini lors de la configuration comme clé et la chaîne de base que vous avez générée à l'étape 2 comme message. Convertissez le résultat au format Base64 pour obtenir la signature attendue.

4. 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.

5. OPTIONNEL

   Pour prévenir les attaques par rejeu, un type d'attaque informatique 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 d'horodatage extraite avec l'horodatage actuel et de s'assurer qu'elle se situe dans une limite de temps raisonnable. Par exemple, une fenêtre de 10 minutes est généralement une bonne limite de temps raisonnable.

Schéma de charge utile

Lorsque l'événement cible de votre webhook est déclenché, il envoie une requête à votre URL de webhook, incluant des informations sur l'événement dans la charge utile. Toutes les charges utiles des requêtes partagent le même schéma qui se compose de champs fixes et variables. Cela garantit que les données transmises dans la charge utile sont structurées et cohérentes, facilitant ainsi le traitement et l'utilisation des données par l'application réceptrice.

Les champs de schéma de charge utile fixes peuvent aider à maintenir la cohérence à travers toutes les requêtes de webhook, avec les champs suivants disponibles :

1. 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 un doublon.
2. EventType (string) : Indique le type d'événement pour lequel la notification a été déclenchée.
3. EventTime (string) : L'horodatage de l'envoi de l'événement.

Les champs de schéma de charge utile variables offrent de la flexibilité aux webhooks pour accueillir divers types d'événements, qui incluent :

1. EventPayload (object) : Contient des informations spécifiques au 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 charge utile de l'événement Demande de Droit à l'Effacement :

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

Gérer les notifications

Si vous stockez des Informations Personnellement Identifiables (PII) de vos utilisateurs, telles que leurs ID Utilisateur, vous devez évaluer la demande à la lumière de vos obligations légales. Plus d'informations peuvent être trouvées dans RTBF et Créateurs. Vous pouvez créer un bot pour gérer les notifications par webhook et aider à automatiser la suppression des données, à condition que vous stockiez des PII dans un magasin de données. Consultez Automatiser la Suppression des Demandes de Droit à l'Effacement pour un exemple de création d'un bot dans Discord qui utilise l'API Open Cloud 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 de terminaison personnalisé comme serveur webhook au lieu d'un outil tiers, vous pouvez extraire les données soumises à suppression de la charge utile du webhook et construire votre propre solution d'automatisation. L'exemple de code suivant est un exemple d'un serveur qui a une prévention contre les attaques par rejeu en vérifiant l'horodatage et que la requête provient de Roblox :

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

const secret = '<your_secret>' // Cela peut être défini comme une variable d'environnement

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

app.all('/*', function (req, res) {
   console.log('Nouvelle requête reçue');

   // Extraire l'horodatage et la signature de l'en-tête
   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);

   // Assurez-vous que la requête est arrivée dans une fenêtre de 300 secondes pour prévenir les attaques par rejeu
   const requestTimestampMs = timestamp * 1000;
   const windowTimeMs = 300 * 1000;
   const oldestTimestampAllowed = Date.now() - windowTimeMs;

   if (requestTimestampMs < oldestTimestampAllowed) {
      return res.status(403).send('Requête Expirée');
   }

   // Valider la 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('Requête Non Autorisée');
   }

   // Votre logique pour gérer la charge utile
   const payloadBody = req.body;
   const eventType = payloadBody['EventType'];

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

      console.log(`Données de la charge utile : UserId=${userId} et GameIds=${gameIds}`);
      // Si vous stockez des PII dans des magasins de données, utilisez l'UserId et les GameIds pour supprimer les informations des magasins de données.
   }

   return res.json({ message: 'Message traité avec succès' });
});

app.listen(8080, function () {
   console.log('Serveur démarré');
});