API WhatsApp et les webhooks : guide pour les outils de marketing automation

Un webhook WhatsApp API est un mécanisme de notification HTTP par lequel Meta envoie des événements en temps réel à votre serveur : livraison d'un message, lecture, réponse d'un contact, changement de statut d'un numéro. Pour un outil de marketing automation, ces webhooks sont le point d'entrée de toute logique de séquençage : une réponse "OUI" déclenche un upsell, un statut "read" met à jour le score d'engagement, un échec de livraison bascule vers un canal de secours. Sans webhooks bien gérés, WhatsApp devient un canal aveugle.

Les types d'événements webhook WhatsApp à connaître

Meta envoie plusieurs familles d'événements vers votre endpoint de callback. Votre outil de marketing automation doit les différencier pour déclencher les bonnes actions.

Événements de statut de message :

Événement	Signification	Action recommandée
sent	Message accepté par Meta	Mettre à jour le statut en base
delivered	Message livré sur le téléphone	Incrémenter le compteur de livraison
read	Message lu par le contact	Déclencher un segment "engagé"
failed	Échec d'envoi	Analyser le code d'erreur, basculer canal

Événements de message entrant :

Type	Exemple	Action
text	Réponse libre du contact	Routing vers chatbot ou agent
button	Clic sur un bouton de template	Déclencher le workflow associé
list_reply	Sélection dans une liste interactive	Personnaliser la suite du parcours
reaction	Emoji posé sur un message	Mesure d'engagement passif

Événements système :

• phone_number_quality_update : changement de quality rating.
• account_update : modification du statut du compte WABA.
• template_status_update : approbation ou rejet d'un template par Meta.

Configurer l'endpoint de réception

Meta impose des conditions techniques précises sur l'endpoint qui reçoit les webhooks :

Vérification de l'endpoint (handshake) :

Lors de l'enregistrement du webhook, Meta envoie une requête GET avec un paramètre hub.challenge. Votre endpoint doit retourner ce challenge pour prouver qu'il contrôle l'URL. Cela n'arrive qu'une fois, à l'enregistrement ou lors d'un changement d'URL.

Traitement des requêtes POST :

Meta envoie les événements en POST avec un payload JSON. Votre endpoint doit :

1. Répondre 200 OK immédiatement (dans les 20 secondes, sinon Meta considère l'événement comme non livré).
2. Traiter le payload de façon asynchrone (via queue).
3. Vérifier la signature HMAC-SHA256 pour s'assurer que la requête vient bien de Meta.

Idempotence :

Meta peut renvoyer le même événement plusieurs fois. Votre système doit gérer les doublons : stockez le message_id de chaque événement et ignorez les répétitions.

Pour une configuration complète de l'endpoint webhook, notre guide sur la configuration et réception des webhooks WhatsApp couvre chaque étape.

Patterns de marketing automation avec les webhooks WhatsApp

Les webhooks transforment WhatsApp d'un canal d'envoi en une boucle de rétroaction. Voici les patterns les plus utiles pour un outil d'automation :

Séquence de nurturing déclenchée par une réponse :

1. Envoi d'un message template avec bouton "En savoir plus".
2. Webhook button reçu → déclenche l'envoi du message suivant avec plus de détails.
3. Si pas de réponse en 48h → webhook silence détecté → basculer vers email de relance.

Scoring d'engagement en temps réel :

• delivered : +1 point d'engagement.
• read : +3 points.
• button_click : +10 points.
• failed : −5 points, révision de l'opt-in.

Ce score peut alimenter un segment dans votre CRM pour personnaliser les prochains messages.

Détection des désabonnements :

Un webhook text avec le contenu "STOP" ou "Désabonner" doit immédiatement déclencher la mise à jour du statut opt-in du contact. Votre outil doit parser le message entrant pour détecter ces termes, quelle que soit la langue ou la casse.

Qualification conversationnelle :

Un contact répond à un message de bienvenue par une question libre → le webhook text déclenche un chatbot qui pose des questions de qualification → les réponses alimentent les propriétés CRM du contact.

Pour comprendre quels templates déclenchent ces interactions, consultez notre article sur les templates WhatsApp et leurs catégories.

Ce que Whakup simplifie dans l'architecture webhook

Gérer les webhooks Meta directement présente plusieurs défis : une seule URL de callback par app, gestion des re-livraisons, parsing de payloads complexes. Whakup abstrait une partie de cette complexité.

Avec l'API REST et les webhooks Whakup :

• Webhooks normalisés : Whakup transforme les payloads Meta bruts en événements structurés et cohérents, plus simples à intégrer dans votre outil d'automation.
• Multi-tenant natif : les événements sont routés par numéro/tenant, sans que vous ayez à implémenter ce routing vous-même.
• Retry managé : en cas de timeout de votre endpoint, Whakup gère la re-livraison des événements avec un backoff progressif.
• Hébergement EU : les webhooks sont émis depuis une infrastructure européenne, ce qui réduit la latence pour les outils hébergés en France ou en Europe.

Whakup est Meta Tech Provider certifié : pas de certification propre à passer, pas de processus d'audit Meta à gérer de votre côté.

Commencez à construire vos séquences d'automation sur la page d'intégration de l'API WhatsApp Whakup.

FAQ

Combien de fois Meta re-livre-t-il un événement si mon endpoint ne répond pas ?

Meta tente de re-livrer les événements pendant 7 jours avec un backoff exponentiel. Si votre endpoint reste indisponible au-delà, les événements sont perdus. C'est pourquoi votre endpoint doit répondre 200 OK immédiatement, même si le traitement réel se fait en asynchrone.

Peut-on avoir plusieurs URLs de webhook sur la même app Meta ?

Non, Meta n'autorise qu'une seule URL de callback par application. Si vous devez envoyer les événements vers plusieurs systèmes (CRM + analytics), vous devez implémenter un fan-out depuis votre endpoint : une URL reçoit tout, puis redistribue.

Comment tester les webhooks en développement sans exposer un serveur public ?

Utilisez des outils comme ngrok ou Cloudflare Tunnel pour exposer votre serveur local sur une URL HTTPS publique. Meta exige HTTPS avec un certificat valide — les URLs en HTTP ou avec des certificats auto-signés sont rejetées.

Les webhooks WhatsApp fonctionnent-ils en temps réel ?

La latence est généralement inférieure à 1 seconde pour les événements de statut de message. Les messages entrants arrivent en temps réel. Des pics de latence peuvent survenir lors d'incidents d'infrastructure Meta, mais c'est rare. Pour les séquences critiques, implémentez un mécanisme de détection des délais anormaux.