API WhatsApp et les webhooks : guide pour les intégrateurs

Les webhooks de l'API WhatsApp Business sont les événements temps réel que Meta envoie à votre serveur pour signaler toute activité sur vos comptes : messages entrants, statuts de livraison, changements de qualité, mises à jour de templates. Pour un intégrateur qui construit une application au-dessus de l'API WhatsApp, la maîtrise des webhooks est aussi importante que la maîtrise des appels API sortants — c'est le système nerveux de votre intégration.

Architecture des webhooks Meta

Les webhooks Meta fonctionnent selon un modèle push HTTPS. Quand un événement survient (message reçu, message livré, template approuvé), Meta envoie une requête HTTP POST vers l'URL que vous avez configurée sur votre application Meta.

Configuration requise :

• Une URL HTTPS publiquement accessible (pas de localhost)
• Un endpoint qui répond avec un statut HTTP 200 en moins de 20 secondes
• Un token de vérification (choisi par vous) pour valider l'abonnement initial via le challenge GET Meta

Abonnement initial : Meta vérifie votre endpoint en envoyant une requête GET avec les paramètres hub.mode=subscribe, hub.challenge, et hub.verify_token. Votre endpoint doit retourner la valeur de hub.challenge si le hub.verify_token correspond au token que vous avez configuré.

Une fois l'abonnement validé, Meta commence à envoyer les événements POST. Si votre endpoint ne répond pas ou retourne une erreur, Meta retente pendant 36 heures avec backoff exponentiel, puis désactive le webhook.

Les événements webhook à implémenter

L'API WhatsApp génère plusieurs familles d'événements. Voici les plus importants pour une intégration complète :

Événement	Champ Meta	Quand c'est déclenché
Message entrant	messages	Un contact envoie un message
Statut "envoyé"	statuses (sent)	Le message a quitté les serveurs Meta
Statut "livré"	statuses (delivered)	Le message est arrivé sur l'appareil du contact
Statut "lu"	statuses (read)	Le contact a ouvert le message
Échec d'envoi	statuses (failed)	Le message n'a pas pu être livré
Template approuvé	message_template_status_update	Meta approuve ou rejette un template
Changement de qualité	phone_number_quality_update	Le quality rating du numéro change
Mise à jour du compte	account_update	Changement sur le WABA (restriction, etc.)

Chaque événement POST contient un objet JSON avec une structure imbriquée. La structure de base est :

{
  "object": "whatsapp_business_account",
  "entry": [{
    "id": "<WABA_ID>",
    "changes": [{
      "value": { ... },
      "field": "messages"
    }]
  }]
}

Sécurisation des webhooks

Un endpoint webhook public non sécurisé peut être exploité pour injecter des faux événements. Meta signe chaque requête POST avec un hash HMAC-SHA256 de la payload, en utilisant votre App Secret comme clé.

Validation de signature :

1. Récupérez le header X-Hub-Signature-256 de la requête entrante
2. Calculez HMAC-SHA256(raw_body, app_secret)
3. Comparez (en comparaison à temps constant pour éviter les timing attacks) le hash calculé avec la valeur du header

Si les hashes ne correspondent pas, rejetez la requête avec un 403. Ne retournez jamais un 200 pour une requête non validée — cela accuse réception d'un événement non authentique.

En plus de la validation de signature, limitez l'accès à votre endpoint via une allowlist d'IPs Meta (disponible dans la documentation Meta for Developers).

Gestion des webhooks dans une architecture multi-tenant

Si vous intégrez l'API WhatsApp pour plusieurs clients (plateforme SaaS, agence multi-comptes), vous avez deux options d'architecture webhook :

Option 1 : Endpoint unique avec routing Un seul endpoint reçoit tous les webhooks de tous les WABA. Le routing vers le bon client se fait sur le champ entry[].id (l'identifiant WABA).

Avantages : configuration Meta simplifiée, un seul endpoint à maintenir. Inconvénients : votre endpoint devient un point de défaillance unique, la charge augmente avec le nombre de clients.

Option 2 : Endpoint par client (ou par groupe) Chaque WABA ou groupe de WABA pointe vers un endpoint différent.

Avantages : isolation des clients, scalabilité horizontale. Inconvénients : plus de configuration, plus d'endpoints à maintenir.

Via l'infrastructure de Whakup — détaillée sur la page de l'API WhatsApp Whakup — vous configurez une URL de webhook dans votre compte Whakup, et Whakup transmet les événements Meta vers votre URL avec enrichissement (identifiants tenant, métadonnées normalisées). Cela vous évite de gérer directement les abonnements Meta et la validation de signature.

Pour la gestion des templates qui déclenchent certains de ces événements, consultez notre article sur les templates WhatsApp pour les intégrateurs.

FAQ

Que faire si mon endpoint webhook est temporairement indisponible ?

Meta retente les webhooks pendant 36 heures avec backoff exponentiel. Si votre endpoint reste indisponible après ce délai, Meta désactive l'abonnement. Vous devez alors réactiver manuellement le webhook dans le Business Manager ou via l'API de configuration. Pour éviter les pertes d'événements, implémentez une queue de messages côté réception (ex. : Redis, SQS, BullMQ) pour traiter les webhooks de façon asynchrone et retourner le 200 rapidement.

Peut-on recevoir les webhooks de plusieurs WABA sur le même endpoint ?

Oui. Les webhooks sont configurés au niveau de l'application Meta, pas au niveau du WABA individuel. Tous les WABA associés à votre app Meta envoient leurs événements vers le même endpoint. Le champ entry[].id permet d'identifier le WABA concerné.

Comment tester les webhooks en développement sans exposer localhost ?

Utilisez un outil comme ngrok, Cloudflare Tunnel, ou localtunnel pour créer un tunnel HTTPS vers votre localhost. Meta nécessite une URL HTTPS valide avec un certificat reconnu — les certificats auto-signés ne sont pas acceptés.

Les webhooks sont-ils garantis "at-least-once" ou "exactly-once" ?

Meta garantit la livraison "at-least-once" : un même événement peut être envoyé plusieurs fois en cas de problème réseau. Votre traitement doit être idempotent — vérifier si l'événement a déjà été traité avant de déclencher une action (via l'id du message ou de l'événement comme clé de déduplication).

---

Bien implémenter les webhooks WhatsApp, c'est garantir la réactivité et la fiabilité de votre intégration. Pour accélérer ce travail, Whakup — Meta Tech Provider certifié — abstrait la complexité de la gestion des abonnements Meta et vous transmet des webhooks normalisés, prêts à consommer. Consultez la documentation ou contactez-nous pour démarrer votre intégration.