Webhooks

Un webhook est une URL spécifiée par le partenaire sur laquelle la plate-forme RBM publie des messages et des événements. Cette URL sert de point de terminaison qui reçoit des requêtes POST HTTPS 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 webhooks d'agent

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

  • Le webhook de votre 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 du partenaire.
  • Les webhooks d'agent s'appliquent à des agents individuels. Si vous gérez plusieurs agents avec un comportement distinct, vous pouvez définir un webhook différent pour chaque agent.

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

Configurer un webhook d'agent

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

  1. Ouvrez la console de développement Business Communications 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 URL du point de terminaison du webhook, saisissez l'URL de votre webhook commençant par "https://".
  6. Notez la valeur clientToken. Vous en avez besoin pour vérifier que les messages que vous recevez proviennent de Google.
  7. Configurez votre webhook pour qu'il accepte une requête POST avec le paramètre clientToken spécifié et qu'il renvoie une réponse 200 OK avec la valeur en texte brut du paramètre secret comme corps de la réponse.

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

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

    Votre webhook doit alors confirmer la valeur clientToken et, si clientToken est correct, renvoyer une réponse 200 OK avec 1234567890 comme corps de la 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 que Google a bien 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 la charge utile RBM en base64 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 la configuration de votre webhook) comme clé, créez un HMAC SHA512 des octets de la charge utile du message décodée en base64 et encodez le résultat en base64.
  4. Comparez le hachage X-Goog-Signature au hachage que vous avez créé.
    • Si les hachages correspondent, vous confirmez que Google a bien envoyé le message.
    • Si les hachages ne correspondent pas, vérifiez votre processus de hachage sur un message connu.

      Si votre processus de hachage fonctionne correctement et que vous recevez un message qui, selon vous, vous a é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);
  

Traitement des messages

Tout autre valeur renvoyée à partir d'un webhook que 200 OK est considérée comme un échec de diffusion.

Les développeurs doivent garder à l'esprit que l'envoi de messages à un débit élevé génère des notifications webhook à un débit élevé. Ils doivent concevoir leur code pour s'assurer qu'ils peuvent consommer les notifications au débit 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 avant expiration ou les échecs en amont. Voici quelques points à prendre en compte:

  • Assurez-vous que vos protections DDoS sont configurées pour gérer le débit attendu des notifications webhook.
  • Assurez-vous que les ressources telles que les pools de connexion de base de données ne s'épuisent pas et ne produisent pas d'expirations ni de réponses 500.

Comportement en cas d'échec de diffusion

RBM utilise un mécanisme de délai avant réessai lorsqu'il reçoit une réponse autre que 200 OK à partir d'un appel de webhook. RBM augmente le temps d'attente entre les nouvelles tentatives jusqu'à 600 secondes au maximum. Les tentatives de nouvelle envoi 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. 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 auprès des autres webhooks. Les webhooks appartenant à d'autres agents seront appelés pendant la période de délai avant réessai d'un message ayant échoué. Toutefois, à mesure que les messages ayant échoué sont mis en file d'attente pour une nouvelle tentative, les taux de diffusion 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 réduire les risques de retour d'une erreur.

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