API WhatsApp et les webhooks : guide pour les plateformes emailing

Une plateforme emailing sait gérer les webhooks : bounces, ouvertures, clics, désabonnements. Intégrer l'API WhatsApp Business suit la même logique, mais le contrat technique est différent. Les webhooks WhatsApp transmettent des événements en temps réel sur les messages envoyés et reçus, avec une structure JSON spécifique que votre backend doit interpréter correctement. Ce guide couvre ce que les équipes techniques des plateformes emailing doivent savoir pour implémenter les webhooks WhatsApp sans surprises.

Qu'est-ce qu'un webhook WhatsApp et pourquoi c'est critique

Dans l'API WhatsApp Business, les webhooks sont le seul mécanisme pour recevoir des informations en retour. Contrairement à une API pull (vous interrogez l'API pour obtenir des données), WhatsApp pousse les événements vers votre endpoint HTTPS en temps réel.

Ce que les webhooks transmettent :

Type d'événement	Déclencheur
message	Un utilisateur vous envoie un message entrant
status: sent	Le message a quitté les serveurs WhatsApp
status: delivered	Le message est arrivé sur l'appareil du destinataire
status: read	Le destinataire a ouvert le message
status: failed	L'envoi a échoué (numéro invalide, blocage, etc.)
status: deleted	Le destinataire a supprimé le message

Pour une plateforme emailing qui ajoute WhatsApp comme canal, ces statuts sont l'équivalent des événements de tracking email (livraison, ouverture, clic). Ils doivent alimenter vos tableaux de bord de performance campagne de la même façon.

La différence fondamentale : WhatsApp vous donne un taux de "read" réel. Contrairement aux pixels de tracking email (bloqués par de nombreux clients mail), le statut "read" WhatsApp est natif et fiable.

Configuration technique du webhook WhatsApp

La configuration d'un webhook WhatsApp passe par le Meta Business Manager ou via l'API. Les prérequis techniques :

Votre endpoint HTTPS doit :

• Répondre en moins de 5 secondes à chaque événement (sinon Meta considère l'endpoint indisponible).
• Retourner un code HTTP 200 pour confirmer la réception.
• Vérifier la signature HMAC-SHA256 de chaque requête pour s'assurer qu'elle vient bien de Meta.
• Gérer les requêtes en idempotence (Meta peut renvoyer le même événement plusieurs fois en cas d'échec de livraison).

Étapes de configuration :

1. Enregistrez votre endpoint dans le Meta Business Manager (URL + token de vérification).
2. Meta envoie une requête GET de vérification avec un challenge que votre endpoint doit renvoyer.
3. Sélectionnez les champs d'événements que vous souhaitez recevoir (messages, statuts, etc.).
4. Testez avec l'outil de débogage Meta.

Pour les plateformes qui passent par un Meta Tech Provider certifié comme Whakup, cette configuration est simplifiée : l'API WhatsApp Business expose un mécanisme de webhook management qui abstrait une partie de la configuration Meta.

Structure JSON des événements webhook

Comprendre la structure des payloads est indispensable pour un parsing fiable.

Exemple de payload statut "read" :

{
  "object": "whatsapp_business_account",
  "entry": [{
    "id": "WHATSAPP_BUSINESS_ACCOUNT_ID",
    "changes": [{
      "value": {
        "messaging_product": "whatsapp",
        "statuses": [{
          "id": "MESSAGE_ID",
          "status": "read",
          "timestamp": "1693000000",
          "recipient_id": "33612345678"
        }]
      },
      "field": "messages"
    }]
  }]
}

Exemple de payload message entrant :

{
  "object": "whatsapp_business_account",
  "entry": [{
    "changes": [{
      "value": {
        "messages": [{
          "from": "33612345678",
          "id": "MESSAGE_ID",
          "timestamp": "1693000000",
          "text": { "body": "Je souhaite me désabonner" },
          "type": "text"
        }]
      }
    }]
  }]
}

Pour les plateformes emailing, le point d'attention est la gestion des messages entrants de type "opt-out". Si un utilisateur envoie "STOP" ou une formulation équivalente, votre système doit traiter ce signal comme un désabonnement WhatsApp et ne plus envoyer de messages proactifs à ce numéro.

Consultez le guide complet de l'API WhatsApp Business pour la référence complète des types d'événements et des structures de payload.

Intégration des webhooks dans une plateforme emailing multi-canal

Pour une plateforme emailing qui ajoute WhatsApp comme canal supplémentaire, les webhooks doivent s'intégrer dans l'infrastructure événementielle existante.

Pattern d'intégration recommandé :

1. Endpoint dédié par canal : créez un endpoint /webhooks/whatsapp distinct de vos webhooks email. Les structures de payload sont trop différentes pour être mutualisées sans complexité inutile.
2. Queue asynchrone : le webhook répond immédiatement 200 et publie l'événement dans une queue (Kafka, RabbitMQ, SQS). Le traitement se fait en arrière-plan pour respecter le timeout de 5 secondes.
3. Mapping vers votre modèle de données : créez un mapper qui traduit les événements WhatsApp vers votre modèle interne d'événements de message (envoyé, livré, lu, échoué, réponse entrante).
4. Gestion des doublons : indexez les message_id Meta pour dédupliquer les événements renvoyés.

Pour les plateformes qui gérent plusieurs clients finaux sur une même infrastructure, chaque compte client doit avoir son propre webhook URL (ou partager un webhook avec un routage par WHATSAPP_BUSINESS_ACCOUNT_ID). Le guide Meta Tech Provider détaille comment structurer cette architecture multi-tenant.

Gestion des erreurs et des cas limites

Les webhooks WhatsApp ont des comportements spécifiques à anticiper :

• Retry automatique : si votre endpoint ne répond pas en 200, Meta relance l'envoi jusqu'à 10 fois sur une période de 24h. Vos logs doivent permettre d'identifier les événements en double.
• Statut "failed" : le payload inclut un code d'erreur et un message. Cartographiez les codes d'erreur Meta vers vos propres codes d'erreur internes pour uniformiser les reportings.
• Numéros invalides : l'erreur 131026 indique que le numéro de destination n'a pas de compte WhatsApp actif. Traitez-la comme un bounce définitif, au même titre qu'un hard bounce email.
• Taux d'optout élevé : si un numéro expéditeur génère trop de signalements de spam, Meta peut le rétrograder en qualité "rouge" et limiter ses envois. Monitorez la qualité de vos numéros via l'API.

Pour comparer les options d'infrastructure et les niveaux de service des différents BSP WhatsApp, consultez le comparatif des meilleurs BSP WhatsApp en France.

FAQ

Combien de temps Meta conserve-t-il les événements webhook non délivrés ?

Meta tente de délivrer les événements pendant 24 heures. Au-delà, l'événement est perdu. Il est donc critique que votre endpoint soit hautement disponible. En cas de maintenance planifiée, redirigez le webhook vers un endpoint de stockage temporaire.

Peut-on tester les webhooks WhatsApp sans envoyer de vrais messages ?

Oui. L'outil de test de webhooks dans le Meta Business Developer Panel permet de simuler des payloads et de vérifier que votre endpoint répond correctement. En local, utilisez un tunnel HTTPS (ngrok, Cloudflare Tunnel) pour exposer votre serveur de développement.

Comment gérer les messages entrants qui ne sont pas des réponses attendues ?

Implémentez un handler par défaut qui répond au message entrant avec un message de type "Je ne comprends pas cette réponse. Pour vous désabonner, répondez STOP. Pour nous contacter, appelez le [numéro]." Ce handler catch-all évite de laisser les messages sans réponse, ce qui dégrade la qualité du numéro expéditeur.

Quelle est la différence entre les webhooks en mode Cloud API et en mode On-Premise ?

La Cloud API (solution hébergée par Meta) et l'On-Premise API (solution hébergée en interne) ont des mécanismes de webhook légèrement différents. Les Meta Tech Providers comme Whakup utilisent la Cloud API, qui est plus simple à configurer et maintenir. L'On-Premise est déprécié et n'est plus recommandé pour les nouvelles intégrations.

---

Maîtriser les webhooks WhatsApp est le prérequis technique pour construire un canal WhatsApp fiable dans votre plateforme emailing. Whakup, Meta Tech Provider certifié, vous donne accès à l'API WhatsApp Business avec une couche d'abstraction sur la configuration des webhooks, un monitoring des événements et un hébergement conforme RGPD en EU. Vous intégrez le canal sans reconstruire l'infrastructure Meta depuis zéro.