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.
- Ouvrez la console de développement Business Communications et connectez-vous avec votre compte Google de partenaire RBM.
- Cliquez sur votre agent.
- Cliquez sur Integrations (Intégrations).
- Pour Webhook, cliquez sur Configurer.
- Dans URL du point de terminaison du webhook, saisissez l'URL de votre webhook commençant par "https://".
- Notez la valeur
clientToken
. Vous en avez 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ètreclientToken
spécifié et qu'il renvoie une réponse200 OK
avec la valeur en texte brut du paramètresecret
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, siclientToken
est correct, renvoyer une réponse200 OK
avec1234567890
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); });
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:
- 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 la charge utile RBM en base64 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 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.
- 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.