Webhooks WhatsApp : recevoir les statuts et messages entrants

Les webhooks WhatsApp Business API sont des notifications HTTP que Meta envoie à votre endpoint dès qu'un événement se produit : message livré, lu, réponse d'un utilisateur, changement de statut d'un template, mise à jour du quality rating. Sans webhooks correctement configurés, votre plateforme est aveugle en temps réel — elle doit polluer l'API pour obtenir des informations qui auraient pu être poussées automatiquement. Pour tout éditeur SaaS ou agence, la configuration des webhooks est une étape fondatrice de l'intégration.

Structure d'un payload webhook WhatsApp

Meta envoie tous les événements au même endpoint via des requêtes POST. Le payload JSON suit une structure commune, avec un champ object toujours égal à whatsapp_business_account et un tableau entry contenant les événements.

Exemple de statut de livraison :

{
  "object": "whatsapp_business_account",
  "entry": [{
    "id": "WABA_ID",
    "changes": [{
      "value": {
        "messaging_product": "whatsapp",
        "metadata": { "phone_number_id": "PHONE_ID" },
        "statuses": [{
          "id": "wamid.XXXXX",
          "status": "delivered",
          "timestamp": "1718800000",
          "recipient_id": "33XXXXXXXXX"
        }]
      },
      "field": "messages"
    }]
  }]
}

Exemple de message entrant :

{
  "object": "whatsapp_business_account",
  "entry": [{
    "id": "WABA_ID",
    "changes": [{
      "value": {
        "messages": [{
          "from": "33XXXXXXXXX",
          "id": "wamid.XXXXX",
          "timestamp": "1718800000",
          "text": { "body": "Bonjour, j'ai une question." },
          "type": "text"
        }]
      },
      "field": "messages"
    }]
  }]
}

Les types d'événements à traiter

Type d'événement	Champ dans le payload	Usage principal
Message envoyé	statuses[].status = "sent"	Confirmation d'envoi côté API
Message livré	statuses[].status = "delivered"	Preuve de livraison sur l'appareil
Message lu	statuses[].status = "read"	Calcul du taux de lecture
Erreur d'envoi	statuses[].status = "failed"	Gestion des erreurs, retry
Message entrant texte	messages[].type = "text"	Gestion des réponses
Message entrant bouton	messages[].type = "button"	Tracking des CTA
Message entrant interactif	messages[].type = "interactive"	Réponses aux listes/boutons
Opt-out	messages[].text.body = "STOP"	Gestion des désabonnements
Changement de quality rating	value.phone_number_quality_updates	Alertes de conformité

Configuration technique : les étapes clés

1. Exposer un endpoint HTTPS valide

Meta exige un endpoint en HTTPS avec un certificat SSL valide (pas d'auto-signé). L'URL doit être accessible publiquement. Lors de la configuration initiale, Meta envoie une requête GET avec un hub.challenge que votre endpoint doit retourner pour valider l'abonnement.

GET /webhook?hub.mode=subscribe&hub.verify_token=VOTRE_TOKEN&hub.challenge=CHALLENGE_CODE
→ Répondre avec le CHALLENGE_CODE

2. Vérifier la signature des payloads

Meta signe chaque payload avec votre App Secret via HMAC-SHA256. Vérifiez systématiquement la signature avant de traiter le payload :

X-Hub-Signature-256: sha256=HASH

Ne jamais traiter un webhook non signé ou avec une signature invalide : risque d'injection de faux événements.

3. Répondre en moins de 20 secondes

Meta attend un code HTTP 200 en moins de 20 secondes. Au-delà, il considère la livraison comme échouée et retente. Si votre traitement métier est long (mise à jour base de données, déclenchement de workflow), retournez 200 immédiatement et traitez de façon asynchrone.

4. Gérer l'idempotence

Meta peut livrer le même événement plusieurs fois en cas de problème réseau. Chaque message possède un wamid unique. Stockez les wamid déjà traités pour éviter les doublons (mise à jour de statut en double, déclenchement de workflow en double).

Architecture recommandée pour les éditeurs SaaS

Pour une plateforme multi-clients, un seul endpoint webhook peut recevoir les événements de tous vos clients. Le routing se fait via le champ WABA_ID ou phone_number_id dans le payload.

Endpoint unique → File d'attente (Redis/SQS) → Workers par client → Base de données

Ce pattern découple la réception des événements de leur traitement, absorbe les pics de trafic et simplifie la gestion des erreurs. Configurez une dead letter queue pour les événements non traités après plusieurs tentatives.

Whakup simplifie cette architecture en proposant des webhooks normalisés et enrichis : les événements Meta bruts sont transformés en un format unifié, et les métadonnées client (identifiant de campagne, numéro d'envoi) sont ajoutées automatiquement dans le payload. Cela réduit le code de routage de votre côté.

Pour une vue complète sur la gestion multi-numéros et multi-clients, consultez notre article sur la gestion de plusieurs numéros WhatsApp via une seule API. Et pour comprendre l'architecture globale de l'API, notre guide complet de l'API WhatsApp Business couvre les fondamentaux.

Cas d'usage métier activés par les webhooks

• Tracking de campagne en temps réel. Calculez le taux de livraison, de lecture et de clic en temps réel dès réception des statuts. Afficher ces métriques dans le dashboard de votre client améliore significativement la valeur perçue de votre plateforme.
• Gestion des opt-out automatisée. Interceptez les mots-clés "STOP", "STOP TOUT", "Unsubscribe" dans les messages entrants et mettez à jour automatiquement le statut opt-out dans votre CRM. Ce flux doit fonctionner sans intervention humaine.
• Déclenchement de workflows conversationnels. Un message entrant peut déclencher un arbre de décision (chatbot léger) ou une alerte à un agent humain. Les webhooks sont le déclencheur de toute logique conversationnelle.
• Alertes quality rating. Les événements de changement de quality rating permettent d'alerter vos clients avant qu'un problème devienne critique.

L'API WhatsApp pour agences et éditeurs Whakup expose tous ces événements via des webhooks configurables par numéro, avec un format de payload documenté et stable.

FAQ

Peut-on abonner plusieurs endpoints à un même WABA ?

Non. Meta ne permet qu'un seul endpoint webhook par application Meta. Si vous avez besoin de distribuer les événements à plusieurs systèmes (CRM, analytics, alerting), gérez ce fan-out dans votre infrastructure après réception du webhook.

Les webhooks sont-ils garantis (at-least-once delivery) ?

Meta garantit une livraison "au moins une fois". En cas de timeout ou d'erreur HTTP de votre côté, Meta retente la livraison. Il n'y a pas de garantie d'ordre des événements. Votre système doit être idempotent et tolérer les événements hors ordre (par exemple, un "read" reçu avant un "delivered").

Comment tester les webhooks en local pendant le développement ?

Utilisez un tunnel HTTPS comme ngrok ou Cloudflare Tunnel pour exposer votre endpoint local. Meta nécessite une URL publique HTTPS même en développement. Alternativement, Whakup propose un environnement sandbox qui permet de simuler des événements webhook sans exposer votre endpoint aux requêtes Meta réelles. Pour en savoir plus, consultez notre article sur la sandbox WhatsApp API.

Quel format de timestamp Meta utilise-t-il dans les webhooks ?

Meta utilise des timestamps Unix (secondes depuis epoch UTC). Convertissez-les systématiquement en UTC avant stockage. Les fuseaux horaires des utilisateurs ne sont pas inclus dans le payload.

---

Les webhooks sont le système nerveux de toute intégration WhatsApp sérieuse. Sans eux, vous perdez la réactivité qui fait la valeur du canal. Configurez-les correctement dès le départ, gérez l'idempotence et construisez votre architecture pour absorber les pics. Pour démarrer avec une infrastructure webhook déjà normalisée, découvrez l'API WhatsApp Whakup Meta Tech Provider certifiée.