Notifications de webhook

Au lieu de surveiller manuellement tous les événements dans 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 afin de 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, comme 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 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é 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établie - 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 à 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 lorsque 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 à l'aide de l'ID de commande de commerce unique.

Configurer des webhooks dans 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 à des groupes, seuls les propriétaires de groupe peuvent configurer et recevoir des notifications de 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 pourrait ressembler à 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 d'événements 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 des URLs de webhook

Vous pouvez configurer un point de terminaison HTTP personnalisé comme votre URL de webhook, à condition qu'il réponde aux exigences suivantes :

• Il doit être accessible publiquement pour gérer 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 les 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 à propos de 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 de 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 cette situation, vous devez mettre à jour la configuration de votre 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 d'assistance ou de documentation de l'outil cible. Pour les outils tiers pris en charge, consultez les 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 le User ID de l'utilisateur qui a déclenché la notification, comme montré ici :

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

Si vous intégrez votre webhook à un service tiers, vous pouvez le tester à l'aide de 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 un 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 un roblox-signature dans chaque notification de webhook pour s'assurer que la requête provient réellement de Roblox. La signature se trouve dans l'en-tête de 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 du moment où la notification a été envoyée :

t=<timestamp>

Pour vérifier une signature :

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

   • t : L'horodatage du moment où la notification a été envoyée.
   • v1 : La valeur de signature générée en utilisant le secret fourni par la configuration du Tableau de Bord Créateur.

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

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

3. Calculez un code d'authentification par 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é correctement la signature, la valeur doit être la même.

5. (Optionnel) Pour éviter les attaques par rejeu, 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 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 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 entre 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 du moment où l'événement a été déclenché.

Les champs de schéma de charge utile variables offrent de la flexibilité aux webhooks pour s'adapter à 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 Personnelles 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 de webhook et aider à automatiser la suppression des données, à condition que vous stockiez des PII dans un magasin de données. Consultez Automatiser les Demandes de Suppression de Droit à l'Effacement pour un exemple sur la façon de créer un bot au sein de Discord qui utilise l'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 de terminaison personnalisé comme votre serveur webhook au lieu d'un outil tiers, vous pouvez extraire les données sujettes à 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 protection contre les attaques par rejeu en vérifiant l'horodatage et en s'assurant 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 a été effectuée dans une fenêtre de 300 secondes pour éviter 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');
   }

   // Validez 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 les 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é');
});