Vérifier un endpoint webhook WhatsApp
Avant de livrer un événement, Meta appelle votre endpoint avec un GET contenant hub.mode, hub.verify_token et hub.challenge. Votre endpoint doit comparer le token et renvoyer le challenge dans le corps brut. Tout autre résultat empêche la livraison de démarrer.
La valeur qui doit être renvoyée comme corps de la réponse.
La valeur de hub.mode lors d’une requête de vérification.
Le seul schéma que Meta vérifie. HTTP est rejeté avant l’appel.
Qu’est-ce que Meta envoie exactement ?
Une requête GET vers votre URL avec trois paramètres de requête. hub.mode est défini sur subscribe. hub.verify_token correspond au token que vous avez configuré lors du paramétrage de la destination. hub.challenge est une valeur générée par Meta pour cette tentative.
Votre endpoint doit comparer hub.verify_token au token choisi et, s’ils correspondent, répondre avec le code 200 et hub.challenge comme corps de réponse complet. Il ne doit pas être enveloppé dans du JSON, ni entouré de guillemets, ni suivi d’un retour à la ligne que certains frameworks ajoutent par défaut.
Si le token ne correspond pas, répondez avec le code 403. C’est tout le protocole, volontairement minimal.
Pourquoi une mauvaise réponse échoue-t-elle en silence ?
Parce qu’un échec de vérification n’est pas une erreur dans votre système, mais une absence dans celui de Meta.
Lorsque le challenge n’est pas renvoyé correctement, Meta ne commence tout simplement pas à livrer les événements à cette destination. Votre serveur renvoie 200 lors de la vérification, vos logs montrent qu’une requête est arrivée, et aucun dashboard ne signale de problème. Le seul symptôme est que les messages n’arrivent jamais, ce que la plupart des équipes attribuent à un problème de Coexistence plutôt qu’à un problème de vérification.
C’est pourquoi il vaut la peine de valider la destination avant l’appel. Nous vérifions que l’URL est en HTTPS et qu’un token de vérification a été fourni avant d’effectuer la requête Graph, afin qu’une destination mal formée échoue immédiatement au lieu de paraître connectée.
Qu’est-ce qui peut encore bloquer la vérification ?
Trois éléments qui n’ont rien à voir avec le code.
Une authentification devant l’endpoint. Une passerelle, une couche d’authentification basique ou une liste d’adresses IP autorisées rejettera la requête de Meta, qui n’a aucun identifiant à présenter. La route de vérification doit être accessible sans authentification.
Une redirection. Meta appelle l’URL que vous lui avez fournie, et une redirection 301 vers un hôte canonique n’est pas suivie d’une façon qui termine l’échange. Fournissez-lui l’URL finale.
Enfin, un framework qui sérialise la réponse. Renvoyer une chaîne depuis un gestionnaire qui enveloppe tout dans du JSON produit un corps entouré de guillemets, qui ne correspond pas au challenge.
Erreurs courantes
- Renvoyer du JSON. Le corps doit contenir uniquement la valeur brute du challenge.
- Placer l’endpoint derrière une authentification. Meta n’a aucun identifiant et la requête sera rejetée.
- Fournir à Meta une URL qui redirige. Utilisez l’URL finale.
EasyCoexistence vérifie qu’une destination est en HTTPS et qu’un token de vérification a été fourni avant d’appeler Meta, puis consigne l’échec de la vérification dans la chronologie de la connexion au lieu d’ignorer la destination.
Questions fréquemment posées
Quel token dois-je utiliser ?
N’importe quelle chaîne de caractères de votre choix. Elle permet à votre endpoint de distinguer la requête de Meta de celle d’un tiers qui aurait découvert l’URL.
À quelle fréquence la vérification a-t-elle lieu ?
Lors de la configuration, puis chaque fois que la destination est définie. Un endpoint fonctionnel n’est pas revérifié à chaque événement.
Puis-je effectuer le test moi-même ?
Oui. Appelez votre propre endpoint avec les trois paramètres et vérifiez que le corps renvoie exactement la valeur du challenge.
Que se passe-t-il si mon serveur était indisponible lors de la vérification ?
L’échange échoue et la destination ne s’active pas. Enregistrez-la de nouveau pour relancer la vérification.
Poursuivre la lecture
Prêt à commencer ?
Configurez WhatsApp Coexistence en quelques minutes, pas en quelques mois. L’application continue de fonctionner sur le téléphone.
Commencer l'essai gratuitVérifié le