Webhooks

Un webhook est une URL spécifiée par un partenaire où la plate-forme RCS for Business publie messages et événements. Cette URL sert de point de terminaison qui reçoit des requêtes HTTPS POST contenant des données sur les événements. Cela signifie que les données sont envoyées à votre application de manière sécurisée via HTTPS.

Une URL de webhook peut se présenter comme suit : https://[your company name].com/api/rbm-events. Une fois que vous avez configuré votre webhook, vous pouvez commencer à recevoir des messages et des événements.

Avertissement : Notez que RCS for Business met en file d'attente les messages d'un partenaire dans une seule file d'attente. Si le webhook d'un agent échoue (ne renvoie pas 200), cela peut avoir un impact sur la diffusion des webhooks de tous les autres agents du même compte partenaire. Pour en savoir plus, consultez Implications des webhooks au niveau de l'agent.

Webhooks de partenaire et webhooks d'agent

Vous pouvez configurer votre webhook au niveau du partenaire ou de l'agent.

• Votre webhook de partenaire s'applique à tous les agents que vous gérez. Si vos agents ont un comportement similaire ou si vous n'avez qu'un seul agent, utilisez le webhook de partenaire.
• Les webhooks d'agent s'appliquent à des agents individuels. Si vous utilisez plusieurs agents avec des comportements distincts, vous pouvez définir un webhook différent pour chaque agent.

Si vous avez configuré à la fois un webhook de partenaire et un webhook d'agent, le webhook d'agent est prioritaire sur son agent spécifique, tandis que le webhook de partenaire s'applique à tous les agents qui n'ont pas leur propre webhook.

Configurer un webhook d'agent

Remarque : Pour créer une intégration de webhook à l'aide de l'API RBM Management, consultez la documentation Créer une intégration de webhook.

Vous recevez les messages envoyés à votre agent dans votre webhook de partenaire. Si vous souhaitez que les messages d'un agent spécifique arrivent dans un autre webhook, définissez un webhook d'agent.

1. Ouvrez la console pour les développeurs RCS for Business et connectez-vous avec votre compte Google partenaire RCS for Business.
2. Cliquez sur votre agent.
3. Cliquez sur Integrations (Intégrations).

4. Dans la section Webhook, cliquez sur Configure (Configurer).

   1. Dans Webhook endpoint (Point de terminaison du webhook), saisissez l'URL de votre webhook en commençant par "https://".
   2. Dans Client token (Jeton client), spécifiez votre valeur clientToken. Vous en avez besoin pour vérifier que les messages que vous recevez proviennent de Google.
   Remarque : Impossible d'afficher votre jeton client actuel pour des raisons de sécurité. Pour créer un jeton client, saisissez une valeur dans le champ correspondant ou cliquez Refresh (Actualiser) pour générer une valeur aléatoire.

5. Configurez votre webhook pour qu'il accepte les requêtes POST avec une charge utile JSON incluant les paramètres clientToken et secret.

   {
     "clientToken":"YOURCLIENTTOKEN",
     "secret":"YOURSECRET"
   }
   

   Pour valider la requête, votre point de terminaison doit renvoyer un code d'état HTTP 200 OK avec la valeur de chaîne brute du paramètre secret dans le corps de la réponse.

   Exemple de configuration de webhook

   Par exemple, si votre webhook reçoit une POST requête avec le contenu de corps suivant :

     {
     "clientToken":"YOURCLIENTTOKEN",
     "secret":"YOURSECRET"
     }
     

   Votre webhook doit alors confirmer la valeur clientToken et, si clientToken est correct, renvoyer une réponse 200 OK avec YOURSECRET comme corps de réponse :

     // clientToken from Configure
     const myClientToken = "YOURCLIENTTOKEN";
   
     // Example endpoint
     app.post("/rbm-webhook", (req, res) => {
       // Use the X-Goog-Webhook-Type header to route requests
       const webhookType = req.header('X-Goog-Webhook-Type');
   
       if (webhookType === 'verification') {
         const msg = req.body;
         if (msg.clientToken === myClientToken) {
             res.status(200).send(msg.secret);
             return;
         }
       }
       res.send(400);
       // Handle other webhook types
     });
     

6. Dans la console pour les développeurs, cliquez sur Verify (Valider). Lorsque vous cliquez sur Verify, Google envoie une requête POST à votre webhook en indiquant les paramètres clientToken et secret dans le corps de la requête. Lorsque RCS for Business valide votre webhook, la boîte de dialogue se ferme.

Identifier les types de requêtes

Pour identifier le type de requête pour toutes les requêtes envoyées à votre webhook, utilisez l'en-tête X-Goog-Webhook-Type.

L'en-tête peut avoir les valeurs suivantes :

• verification : utilisé pour le processus de validation initial du point de terminaison.
• message_callback: utilisé pour les événements liés aux messages, tels que les notifications de saisie ou de diffusion, et les messages entrants des utilisateurs.
• agent_callback: utilisé pour les événements administratifs spécifiques à l'agent, tels que les modifications de l'état de lancement de l'agent.

Vérifier les messages entrants

Étant donné que les webhooks peuvent recevoir des messages de n'importe quel expéditeur, vous devez vérifier que Google a envoyé les messages entrants avant de traiter leur contenu.

Pour vérifier que Google a envoyé un message que vous avez reçu, procédez comme suit :

1. Extrayez l'en-tête X-Goog-Signature du message. Il s'agit d'une copie hachée et encodée en base64 de la charge utile du corps du message.
2. Décodez en base64 la charge utile RCS for Business dans l'élément message.body de la requête.
3. À l'aide du jeton client de votre webhook (que vous avez spécifié lors de sa configuration) comme clé, créez un HMAC SHA512 des octets de la charge utile du message décodé en base64, puis encodez le résultat en base64.
4. Comparez le hachage X-Goog-Signature avec le hachage que vous avez créé.
   • Si les hachages correspondent, vous avez confirmé que Google a envoyé le message.

   • Si les hachages ne correspondent pas, vérifiez votre processus de hachage sur un message dont vous savez qu'il est correct.

     Si votre processus de hachage fonctionne correctement et que vous recevez un message que vous pensez avoir été envoyé de manière frauduleuse, contactez-nous.

Node.js

  if ((requestBody.hasOwnProperty('message')) && (requestBody.message.hasOwnProperty('data'))) {
    // Validate the received hash to ensure the message came from Google RBM
    const headerHash = req.header('X-Goog-Signature');
    const userEventString = Buffer.from(requestBody.message.data, 'base64');
    const hmac = crypto.createHmac('sha512', myClientToken);
    const genHash = hmac.update(userEventString).digest('base64');

    if (headerHash === genHash) {
      const userEvent = JSON.parse(userEventString);
      const webhookType = req.header('X-Goog-Webhook-Type');

      // Route based on the header type
      if (webhookType === 'message_callback') {
        handleMessage(userEvent);
      } else if (webhookType === 'agent_callback') {
        handleAgentEvent(userEvent);
      }
    } else {
      console.log('Hash mismatch - ignoring message');
      res.sendStatus(401);
      return;
    }
  }

  res.sendStatus(200);
  

Gestion des messages

Le renvoi de tout élément autre que 200 OK à partir d'un webhook est considéré comme un échec de diffusion.

Les développeurs doivent savoir que l'envoi de messages à des débits élevés générera des notifications de webhook à des débits élevés. Ils doivent donc concevoir leur code pour gérer les notifications au débit attendu. Il est important que les développeurs tiennent compte des situations susceptibles d'entraîner des réponses d'échec, y compris les réponses 500 de leur conteneur Web, les délais d'attente ou les échecs en amont. Voici quelques points à prendre en compte :

• Vérifiez que vos protections DDoS sont configurées pour gérer le débit attendu des notifications de webhook.
• Vérifiez que les ressources telles que les pools de connexions de base de données ne sont pas épuisées et ne génèrent pas de délais d'attente ni de réponses 500.

Les développeurs doivent concevoir leurs systèmes de sorte que le traitement des événements RBM se produise de manière asynchrone et n'empêche pas le webhook de renvoyer 200 OK.

Il est important de ne pas traiter l'événement RBM dans le webhook lui-même. Toute erreur ou tout retard lors du traitement peut avoir un impact sur le code de retour du webhook :

Comportement en cas d'échec de diffusion

Si votre webhook renvoie un état autre que 200 OK, la plate-forme RCS for Business utilise un mécanisme de backoff et de nouvelle tentative pour rediffuser les données. Cela signifie que le système augmente progressivement le délai entre chaque tentative de diffusion, jusqu'à atteindre une fréquence maximale d'une nouvelle tentative toutes les 10 minutes pour chaque message en attente. Le cycle de nouvelles tentatives se poursuit pendant sept jours, après quoi le message est définitivement supprimé.

Implications des webhooks au niveau de l'agent

RCS for Business met en file d'attente les messages d'un partenaire dans une seule file d'attente. Tous les agents d'un même compte partenaire partagent une seule file d'attente. Par conséquent, un échec dans un webhook peut bloquer l'ensemble de la file d'attente, empêchant les événements utilisateur de tous les agents d'atteindre le partenaire.

Plusieurs messages non reconnus peuvent entraîner un pic massif d'événements de nouvelle tentative. Par exemple, si un agent ne reconnaît pas 1 600 accusés de réception et que la fréquence de nouvelles tentatives atteint la limite de 10 minutes, cela peut générer environ 230 000 erreurs potentielles par jour :

1 600 messages × 6 nouvelles tentatives par heure × 24 heures par jour = environ 230 000 erreurs par jour

Ce volume de nouvelles tentatives peut bloquer la file d'attente Pub/Sub partagée et entraîner des retards importants dans la réception des événements utilisateur pour toutes les campagnes d'un partenaire.

Bonnes pratiques

Pour garantir la fiabilité de votre trafic de production et éviter les blocages de file d'attente, suivez ces bonnes pratiques :

• Renvoyez immédiatement 200 OK : le webhook doit recevoir le message, le stocker dans une file d'attente locale et renvoyer une réponse 200 OK en moins de cinq secondes.
• Dissociez le traitement : utilisez des workers d'arrière-plan distincts pour traiter la logique des messages à partir de la file d'attente locale.
• Surveillez les agents de test : traitez les agents de développement comme des agents de production, car ils peuvent également bloquer la file d'attente de partenaire partagée en cas d'échec.
• Comptes dédiés aux tests : utilisez de préférence un compte de développeur pour les agents de production et un compte de développeur dédié pour les agents de test.
• Vérifiez le trafic Google : utilisez le DNS inverse ou l'en-tête X-Goog-Signature plutôt que la liste d'autorisation d'adresses IP fixes, car Google utilise des adresses IP anycast dynamiques. Pour en savoir plus sur la validation manuelle et l'identification des plages d'adresses IP Google, consultez la documentation Valider les requêtes Google et, plus précisément, les fichiers JSON pour les extracteurs déclenchés par l'utilisateur et les extracteurs Google déclenchés par l'utilisateur.

Étapes suivantes

Une fois que vous avez configuré votre webhook, votre agent peut recevoir des messages de vos appareils de test. Envoyez un message pour valider votre configuration.