Verifier une signature webhook WhatsApp

En bref : verifier une signature webhook WhatsApp consiste a prouver que l'evenement HTTP vient bien de l'integration attendue avant de modifier le CRM, creer un ticket ou declencher un agent IA. Cette verification doit se faire sur le corps brut de la requete, avant tout traitement metier.

Pourquoi verifier un webhook WhatsApp ?

Un webhook transporte des evenements : message recu, changement de statut, retour d'un template ou mise a jour technique. Sans verification, une application peut traiter un evenement forge comme s'il venait de WhatsApp. Le risque n'est pas seulement technique : un faux evenement peut creer une mauvaise fiche CRM, declencher une action de support ou polluer les donnees qui alimentent un agent IA.

La documentation de la WhatsApp Business Platform est la reference pour l'integration. Le guide OWASP de securite des webhooks rappelle le principe general : authentifier l'expediteur, verifier l'integrite de la requete, limiter les rejouements et journaliser sans divulguer de secrets.

La regle technique a respecter

Le serveur doit verifier l'en-tete de signature fourni par la plateforme en recalculant une signature sur le corps brut de la requete avec le secret conserve cote serveur. Une comparaison a temps constant est preferable afin de ne pas exposer d'information exploitable sur la signature attendue.

Ne faites jamais cette verification dans le navigateur, dans un scenario no-code qui expose le secret, ou apres avoir modifie le JSON recu. Si le corps est reserialise avant le calcul, la signature peut ne plus correspondre au message d'origine.

Architecture minimale

WhatsApp Business Platform
-> endpoint webhook HTTPS
-> lecture du corps brut
-> verification signature + date/eventuellement anti-rejeu
-> validation du schema attendu
-> journalisation technique
-> workflow CRM, inbox ou agent IA

La verification ne remplace pas le controle metier. Un evenement authentique peut etre incomplet, duplique ou inadapté a une action automatique. Apres la signature, validez donc le type d'evenement, l'identifiant de conversation, les droits de l'action et les regles d'escalade.

Procedure pas a pas

1. Isoler le endpoint de reception

Utilisez un endpoint dedie au webhook, en HTTPS, avec une limite de taille de requete et une reponse rapide. Sa seule responsabilite initiale est de verifier et d'enregistrer l'evenement. Les traitements longs doivent partir ensuite vers une file ou un worker.

2. Lire le corps brut avant le parseur JSON

La signature est calculee sur les octets recus. Conservez donc ce corps brut le temps de la verification. Une fois la verification reussie, parsez le JSON et appliquez votre validation de schema.

3. Comparer la signature attendue

Recuperez le secret depuis une variable d'environnement ou un gestionnaire de secrets. Calculez la signature selon l'algorithme indique dans la documentation du fournisseur, puis comparez-la a l'en-tete recu. Si la verification echoue, renvoyez un refus et n'ecrivez rien dans vos systemes metier.

4. Rendre le traitement idempotent

Un webhook peut etre reemis. Enregistrez l'identifiant d'evenement ou le couple message/statut avant de lancer une action. Une meme notification ne doit pas creer deux tickets ni envoyer deux reponses.

5. Prevoir la supervision

Dans la team inbox WhatsApp, affichez un statut simple : evenement recu, verification validee, traitement termine ou echec a revoir. Les equipes ont besoin d'une explication exploitable, pas du secret ni du contenu brut des en-tetes.

Controle de securite et controle de qualite

| Controle | But | Resultat attendu | |---|---|---| | Signature | Authentifier la source | Rejet immediat si invalide | | Validation de schema | Rejeter une charge inattendue | Aucun champ non attendu ne pilote une action | | Idempotence | Eviter les doublons | Une action metier par evenement logique | | Journalisation | Investiguer sans exposer | Identifiant, resultat et horodatage minimaux | | Escalade | Garder le controle humain | Les cas d'erreur visibles dans l'inbox |

Cette separation est utile lorsque vous reliez WhatsApp au CRM : le guide WhatsApp API, webhooks et CRM couvre la cartographie metier, tandis que cette page se limite a l'authenticite de l'evenement.

Erreurs a eviter

Accepter un webhook parce que l'URL est difficile a deviner

Une URL non publique n'est pas une preuve d'authenticite. Le controle doit reposer sur une verification cryptographique et un secret garde cote serveur.

Declencher l'agent IA avant verification

Un agent IA ne doit jamais voir un evenement non authentifie comme une instruction fiable. La verification doit preceder le routage, le resume et toute ecriture CRM.

Stocker les secrets dans le contenu ou les logs

Le secret de signature ne doit figurer ni dans un article, ni dans un ticket, ni dans un log applicatif. En cas de doute ou de fuite, il faut le faire tourner suivant la procedure du fournisseur.

Checklist de recette

• Un webhook valide est accepte et trace.
• Une signature invalide est refusee sans ecriture CRM.
• Un corps modifie apres signature est refuse.
• Un evenement duplique ne produit pas une seconde action.
• Les erreurs de verification sont visibles pour l'equipe technique sans secret expose.
• Les cas sensibles passent a une personne dans l'inbox.

Pour aller plus loin

• WhatsApp Business API : erreurs webhook
• WhatsApp Cloud API, webhook et n8n
• Journalisation d'un agent IA WhatsApp
• Demander un audit gratuit 30 min