Webhooks

Un webhook est une URL spécifiée par le partenaire où la plate-forme RCS for Business publie des messages et des événements. Cette URL sert de point de terminaison qui reçoit les 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 ressembler à ceci : https://[your company name].com/api/rbm-events. Une fois votre webhook configuré, vous pouvez commencer à recevoir des messages et des événements.

Webhooks de partenaires et d'agents

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

  • Votre webhook 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 aux agents individuels. Si vous gérez plusieurs agents avec des comportements distincts, vous pouvez définir un webhook différent pour chaque agent.

Si vous avez configuré un webhook de partenaire et un webhook d'agent, le webhook d'agent est prioritaire pour 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

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

  1. Ouvrez la console de développeur 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 Configurer.
    1. Dans Point de terminaison du webhook, saisissez l'URL de votre webhook commençant par "https://".
    2. Dans Jeton client, spécifiez votre valeur clientToken. Vous en avez besoin pour vérifier que les messages que vous recevez proviennent de Google.

  5. Configurez votre webhook pour qu'il accepte une requête POST avec le paramètre clientToken spécifié et qu'il envoie une réponse 200 OK avec la valeur en texte brut du paramètre secret comme corps de réponse.

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

    {
  "clientToken":"SJENCPGJESMGUFPY",
  "secret":"1234567890"
}

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

    // clientToken from Configure
const myClientToken = "SJENCPGJESMGUFPY";

// 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 Valider. Lorsque RCS for Business valide votre webhook, la boîte de dialogue se ferme.

Identifier les types de demandes

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 initial de validation des points de terminaison.
  • message_callback : utilisé pour les événements liés aux messages, tels que les notifications de saisie ou de remise, et les messages entrants des utilisateurs.
  • agent_callback : utilisé pour les événements administratifs spécifiques à l'agent, tels que les changements d'é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 qu'un message que vous avez reçu a bien été envoyé par Google, 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. En utilisant le 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 et encodez le résultat en base64.
  4. Comparez le hachage X-Goog-Signature avec celui 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 l'intégrité est avérée.

      Si votre processus de hachage fonctionne correctement et que vous recevez un message qui vous semble frauduleux, 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

Si un webhook renvoie une valeur autre que 200 OK, cela est considéré comme un échec de remise.

Les développeurs doivent être conscients que l'envoi de messages à un rythme élevé générera des notifications de webhook à un rythme élevé. Ils doivent donc concevoir leur code pour gérer les notifications au rythme attendu. Il est important que les développeurs tiennent compte des situations qui peuvent 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 taux attendu de 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 produisent 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.

Traitement asynchrone des Webhooks

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 :

Traitement synchrone des webhooks

Comportement en cas d'échec de la diffusion

Si votre webhook renvoie un état autre que 200 OK, la plate-forme RCS pour les entreprises utilise un mécanisme de backoff et de nouvelle tentative pour renvoyer les données. Cela signifie que le système augmente progressivement le délai entre chaque tentative de remise, jusqu'à atteindre une fréquence maximale d'une nouvelle tentative toutes les 10 minutes pour chaque message en attente. Le cycle de réessai 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 et même 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 confirmés peuvent entraîner un pic important d'événements de nouvelle tentative. Par exemple, si un agent ne confirme pas 1 600 accusés de réception et que la fréquence de réessai 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 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 assurer la fiabilité de votre trafic de production et éviter les blocages de file d'attente, suivez ces bonnes pratiques :

  • Renvoyez immédiatement une réponse 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.
  • Découpler le traitement : utilisez des workers en 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 des partenaires partagée en cas d'échec.
  • Comptes dédiés aux tests : il est préférable d'utiliser 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'adresses IP autorisées 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, en particulier 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 votre webhook configuré, votre agent peut recevoir des messages de vos appareils de test. Envoyez un message pour valider votre configuration.

Suivant
Dialogflow