Notifications par Webhook | Documentation

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é qui peut recevoir des requêtes HTTP. Cela vous aide à automatiser votre flux de travail de gestion des notifications afin de réduire l'effort manuel lié à la gestion des notifications.

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

Flux de travail par Webhook

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 de configurer 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 de réception ou votre point de terminaison personnalisé, qui peut agir en fonction des données incluses dans la charge utile du webhook. Cela pourrait inclure la suppression de données pour la GDPR, 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 renouvelé - 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é

Demande de droit à l'effacement - Lorsqu'un utilisateur soumet une demande de suppression de données dans le cadre du Règlement Général sur la Protection des Données (RGPD).

Commerce

Commande de produit commercial remboursée - Lorsqu'un utilisateur a reçu un remboursement pour sa commande de produit commercial, ou que 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, donc vous devez dédupliquer les événements à l'aide de l'ID de commande commerciale unique.

Configurer les webhooks sur le Tableau de Bord des Créateurs

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 détenus par des groupes, seuls les propriétaires de groupe peuvent configurer et recevoir des notifications par webhook.

Si vous configurez des webhooks et traitez des données personnelles, assurez-vous qu'ils sont conformes au Règlement Général sur la Protection des Données (RGPD).

Pour configurer un webhook :

Sélectionnez votre expérience sur Creator Hub.

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

Saisissez votre URL de webhook et un nom.
(Optionnel) Incluez un secret, qui aide à garantir que les notifications que vous recevez proviennent de Roblox. Pour plus d'informations, voir Vérifier la sécurité des webhooks.
Choisissez une ou plusieurs options dans la liste des déclencheurs pris en charge d'événements pour lesquels vous souhaitez recevoir des notifications.
(Optionnel) Utilisez le bouton Tester la Réponse pour vérifier si votre service peut recevoir une demande d'exemple.
Cliquez sur Enregistrer les Changements.

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

Configurer les URL des webhooks

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

Il doit être accessible publiquement pour le traitement des demandes.
Il doit pouvoir traiter des requêtes POST.
Il doit pouvoir répondre à la demande avec une réponse 2XX dans un délai de 5 secondes.
Il doit pouvoir traiter des 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 à partir 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 à traiter, voir le Schéma de Charge Utile.

Politique de nouvelle tentative 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 cette situation, vous devez mettre à jour votre configuration de webhook avec une nouvelle URL qui est accessible et capable de recevoir des notifications. Pour dépanner et confirmer que votre URL de webhook peut recevoir des notifications avec succès, voir 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, voir les suivants :

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 des Créateurs :

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

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

Schéma de SampleNotification
{
  "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é des webhooks

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 s'assurer que la requête provenait bien 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.

Format de signature avec un secret pour les points de terminaison personnalisés
t=<timestamp>,v1=<signature>

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

Format de signature sans secret pour les points de terminaison personnalisés
t=<timestamp>

Pour vérifier une signature :

Extraire les valeurs de timestamp 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: Le timestamp du moment où la notification a été envoyée.
- v1: La valeur de signature générée à l'aide du secret fourni par la configuration du Tableau de Bord des Créateurs.
Recréer la chaîne de base de roblox-signature en concaténant :
1. Le timestamp sous forme de chaîne.
2. Le caractère de point ..
3. La chaîne JSON du corps de la requête.
Calculer 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 en format Base64 pour obtenir la signature attendue.
Comparez la valeur de signature extraite à la signature attendue. Si vous avez correctement généré la signature, la valeur devrait être identique.
(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 de timestamp 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 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, ce qui facilite le traitement et l'utilisation des données par l'application réceptrice.

Les champs du schéma de charge utile fixes peuvent aider à maintenir la cohérence à travers toutes les requêtes de 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 un doublon.
EventType (string) : Indique le type d'événement pour lequel la notification a été déclenchée.
EventTime (string) : L'horodatage du moment où l'événement a été déclenché.

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

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

L'exemple suivant montre le schéma de la charge utile de l'événement Demande de Droit à l'Effacement :

Exemple de schéma pour une 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 supprimer ces informations lorsqu'un utilisateur soumet une telle demande pour se conformer aux exigences de conformité du droit à l'effacement du RGPD droit à l'effacement. 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 une base de données. Voir Automatisation de la Suppression des Demandes de Droit à l'Effacement pour un exemple de création d'un bot dans Discord qui utilise l' API Cloud Open pour les bases de données pour supprimer les données PII comme solution d'automatisation. Cet exemple peut être adapté pour gérer d'autres notifications, telles que des é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 soumises à suppression à partir de la charge utile webhook et construire votre propre solution d'automatisation. Le code suivant est un exemple d'un serveur qui a une prévention contre les attaques par rejeu en vérifiant le timestamp et que la demande provient de Roblox :

Extraction de PII de la Charge Utile
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 demande reçue');

   // Extraire le timestamp 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);

   // Assurer que la demande est venue 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('Demande 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('Demande 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 bases de données, utilisez l'ID Utilisateur et les IDs de jeu pour supprimer les informations des bases de données.
   }

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

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