API WhatsApp et les webhooks : guide pour les CRM

Les webhooks de l'API WhatsApp Business sont des notifications HTTP POST que Meta envoie en temps réel vers un endpoint de votre serveur dès qu'un événement survient sur un numéro : message entrant, accusé de réception, lecture, changement de statut. Pour un CRM qui intègre WhatsApp, les webhooks sont la colonne vertébrale de toute interaction bidirectionnelle — sans eux, impossible de savoir si un message a été reçu, lu, ou si un client a répondu.

Les types d'événements transmis par les webhooks

L'API WhatsApp Cloud envoie plusieurs catégories d'événements via webhooks. Un CRM doit traiter les suivants en priorité :

Messages entrants (messages) Déclenchés quand un utilisateur envoie un message à votre numéro WhatsApp. Le payload inclut le numéro expéditeur, le contenu du message (texte, média, bouton cliqué, localisation), l'ID du message et le timestamp.

Statuts de livraison (statuses) Déclenchés à chaque changement de statut d'un message sortant :

• sent : message accepté par l'API Meta
• delivered : message reçu sur l'appareil du destinataire
• read : message ouvert par le destinataire
• failed : échec de livraison avec code d'erreur

Changements de compte (account_alerts, phone_number_quality_update) Déclenchés en cas de changement du quality rating ou de restriction d'un numéro. Critiques pour la supervision du parc dans un contexte multi-tenant.

Structure d'un payload webhook WhatsApp

Voici la structure standard d'un événement message entrant :

{
  "object": "whatsapp_business_account",
  "entry": [{
    "id": "WABA_ID",
    "changes": [{
      "value": {
        "messaging_product": "whatsapp",
        "metadata": {
          "display_phone_number": "33601020304",
          "phone_number_id": "PHONE_NUMBER_ID"
        },
        "contacts": [{ "profile": { "name": "Jean Dupont" }, "wa_id": "33600112233" }],
        "messages": [{
          "from": "33600112233",
          "id": "wamid.XXX",
          "timestamp": "1717500000",
          "text": { "body": "Bonjour, je voudrais un devis" },
          "type": "text"
        }]
      },
      "field": "messages"
    }]
  }]
}

Le champ phone_number_id est essentiel dans un contexte multi-tenant : il permet de router l'événement vers le bon client de votre CRM. Sans ce routage, tous les messages entrants atterriraient dans le même flux.

Intégrer les webhooks dans un CRM : architecture recommandée

Endpoint de réception

Votre endpoint doit répondre en HTTP 200 dans les 20 secondes. Si Meta ne reçoit pas de 200, il retente l'envoi avec backoff exponentiel pendant 7 jours. Si votre endpoint est lent, implémentez un pattern "accept and queue" : accusez réception immédiatement, traitez le message en arrière-plan.

Vérification du webhook (challenge)

Lors de la configuration, Meta envoie une requête GET avec les paramètres hub.mode=subscribe, hub.verify_token et hub.challenge. Votre endpoint doit vérifier le token (un secret que vous définissez) et renvoyer la valeur de hub.challenge. C'est le handshake d'activation.

Vérification de l'authenticité des payloads

Meta signe chaque requête webhook avec un hash HMAC-SHA256 dans le header X-Hub-Signature-256. Vérifiez systématiquement cette signature avant de traiter le payload pour éviter les injections de faux événements.

Idempotence

Meta peut envoyer le même événement plusieurs fois (at-least-once delivery). Stockez l'ID de chaque message traité (wamid) et ignorez les doublons. Un CRM qui crée une nouvelle fiche contact à chaque doublon se retrouve rapidement avec des données corrompues.

Pour une vision globale de l'architecture d'intégration WhatsApp, consultez notre guide complet de l'API WhatsApp Business.

Cas d'usage CRM activés par les webhooks

Événement webhook	Action CRM suggérée
Message entrant texte	Créer une nouvelle tâche ou ticket dans le CRM avec le contenu
Message entrant avec bouton cliqué	Déclencher un workflow automatique selon le bouton choisi
Statut read	Marquer le message comme lu dans la fiche contact, mettre à jour le score d'engagement
Statut failed	Alerte dans le CRM, tentative de recontact via un autre canal
Réponse avec mot-clé STOP	Désinscription automatique du contact du canal WhatsApp
Message entrant avec localisation	Enrichir la fiche contact avec la zone géographique

L'intégration des statuts read est particulièrement puissante pour les CRM : elle permet de savoir précisément quels messages ont été lus, ce que ni l'email ni le SMS ne permettent nativement avec une telle fiabilité.

Configuration des webhooks via Whakup

Whakup expose une gestion des webhooks par numéro, ce qui permet à chaque client intégré à votre CRM d'avoir son propre endpoint de réception — ou de partager un endpoint centralisé avec routage par phone_number_id.

L'API Whakup REST permet de configurer, tester et superviser les webhooks sans passer par l'interface Meta Business Manager. Pour les éditeurs CRM qui veulent offrir une expérience d'intégration fluide à leurs clients, cette abstraction réduit considérablement la complexité de l'onboarding.

Pour comparer les options disponibles sur le marché avant de vous engager, consultez notre analyse des Meta Tech Providers WhatsApp.

FAQ

Peut-on configurer plusieurs endpoints webhooks pour le même numéro WhatsApp ?

Non, Meta ne permet qu'un seul endpoint webhook par application (App ID). Pour recevoir les événements dans plusieurs systèmes (CRM + analytics + helpdesk), vous devez implémenter un webhook broker : un service qui reçoit tous les événements et les redistribue vers vos différents systèmes.

Les webhooks fonctionnent-ils pour les messages envoyés depuis l'interface WhatsApp Business App ?

Non. L'API Cloud et l'application WhatsApp Business sont des canaux distincts. Un numéro enregistré sur l'API ne peut pas être utilisé simultanément sur l'app mobile. Les webhooks ne reçoivent que les événements relatifs aux messages gérés via l'API.

Que se passe-t-il si mon endpoint est hors ligne pendant plusieurs heures ?

Meta retente la livraison pendant 7 jours avec un backoff progressif. Si votre endpoint reste inaccessible au-delà de ce délai, les événements non délivrés sont perdus définitivement. Il est recommandé de mettre en place une alerte monitoring sur le taux de réponse de votre endpoint webhook.

Comment distinguer un message entrant d'une réponse dans une conversation existante ?

Le champ context dans le payload message contient le wamid du message auquel l'utilisateur répond. Si context est présent, c'est une réponse directe. S'il est absent, c'est un nouveau message initié par l'utilisateur. Cette distinction permet de maintenir le fil de conversation dans votre CRM.

---

Les webhooks WhatsApp sont ce qui transforme un canal d'envoi en canal relationnel. Pour un CRM, les exploiter pleinement — statuts de lecture, réponses, événements de compte — c'est ce qui justifie le passage au canal WhatsApp face à l'email ou au SMS. Whakup, Meta Tech Provider certifié avec hébergement EU, vous fournit des webhooks stables, documentés et observables. Découvrez l'intégration complète sur notre page API WhatsApp Business.