Webhooks

Un webhook est une URL spécifiée par le partenaire où la plate-forme RBM 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 partenaire et 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'en avez qu'un seul, utilisez le webhook partenaire.
  • Les webhooks d'agent s'appliquent aux 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 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 Business Communications Developer Console et connectez-vous avec votre compte Google de partenaire RBM.
  2. Cliquez sur votre agent.
  3. Cliquez sur Integrations (Intégrations).
  4. Pour Webhook, cliquez sur Configurer.
  5. Dans le champ URL du point de terminaison du webhook, saisissez l'URL de votre webhook en commençant par "https://".
  6. Notez votre valeur clientToken. Vous en avez besoin pour vérifier que les messages que vous recevez proviennent bien de Google.

  7. Configurez votre webhook pour qu'il accepte une requête POST avec le paramètre clientToken spécifié et 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) => {
  const msg = req.body;
  if (msg.clientToken === myClientToken) {
      res.status(200).send(msg.secret);
      return;
  }
  res.send(400);
});

  8. Dans la console pour les développeurs, cliquez sur Valider. Lorsque RBM valide votre webhook, la boîte de dialogue se ferme.

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 RBM 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 le bon fonctionnement est avéré.

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

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 pouvant 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 connexion à la 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 la diffusion

RBM utilise un mécanisme de backoff et de nouvelle tentative lorsqu'il reçoit une réponse autre que 200 OK d'un appel de webhook. RBM augmente le temps d'attente entre les nouvelles tentatives jusqu'à un maximum de 600 secondes. Les tentatives se poursuivront pendant sept jours, après quoi le message sera abandonné.

Implications des webhooks au niveau de l'agent

RBM met en file d'attente les messages d'un partenaire dans une seule file d'attente. Lorsqu'un partenaire utilise des webhooks au niveau de l'agent, il est important de garder à l'esprit que l'échec d'un webhook aura un impact sur la diffusion vers d'autres webhooks. Les webhooks appartenant à d'autres agents seront appelés pendant la période de backoff d'un message ayant échoué. Toutefois, à mesure que les messages ayant échoué sont mis en file d'attente pour être réessayés, les taux de remise globaux diminuent et d'autres agents sont affectés.

Il est important que les développeurs comprennent ce modèle et codent en conséquence. Dans la mesure du possible, ils doivent accepter les messages et les mettre en file d'attente pour traitement afin de minimiser les risques d'échec.

É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