Webhooks

Un webhook est une URL spécifiée par le 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.

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

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.

Ouvrez la Business Communications Developer Console et connectez-vous avec votre compte Google partenaire RCS for Business.
Cliquez sur votre agent.
Cliquez sur Integrations (Intégrations).
Pour Webhook, cliquez sur Configure (Configurer).
Pour Webhook endpoint URL (URL du point de terminaison du webhook), saisissez l'URL de votre webhook en commençant par "https://".
Notez la valeur de votre clientToken. Vous en aurez besoin pour vérifier que les messages que vous recevez proviennent de Google.
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 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) => {
  const msg = req.body;
  if (msg.clientToken === myClientToken) {
      res.status(200).send(msg.secret);
      return;
  }
  res.send(400);
});
```
Dans la Developer Console, cliquez sur Verify (Valider). Lorsque RCS for Business valide votre webhook, la boîte de dialogue se ferme.

Valider 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 :

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.
Décodez en base64 la charge utile RCS for Business dans l'élément message.body de la requête.
À 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 et encodez le résultat en base64.
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
    let userEventString = Buffer.from(requestBody.message.data, 'base64');
    let hmac = crypto.createHmac('sha512', CLIENT_TOKEN);
    let data = hmac.update(userEventString);
    let genHash = data.digest('base64');
    let headerHash = req.header('X-Goog-Signature');

    if (headerHash === genHash) {
      let userEvent = JSON.parse(userEventString);

      console.log('userEventString: ' + userEventString);
      handleMessage(userEvent);
    } else {
      console.log('hash mismatch - ignoring message');
    }
  }

  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.
Assurez-vous 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.

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 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 bloqueurs 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 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 l'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 de 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 déclenchés par l'utilisateur Google.

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

Dialogflow