API WhatsApp et les webhooks : guide pour les plateformes SMS

Les webhooks de l'API WhatsApp Business sont des notifications HTTP que Meta pousse en temps réel vers l'endpoint de votre plateforme dès qu'un événement se produit sur un compte WhatsApp Business : message entrant, accusé de réception, changement de statut de numéro, mise à jour du quality rating. Pour une plateforme SMS qui intègre WhatsApp, les webhooks sont l'équivalent des DLR (Delivery Reports) et des MO (Mobile Originating) : ils sont au cœur de l'expérience temps réel.

Événements webhook disponibles sur l'API WhatsApp

Meta classe les événements en plusieurs catégories. Voici les principaux qu'une plateforme SMS doit implémenter :

Événement	Objet JSON	Usage principal
messages	Message entrant (réponse, opt-in, STOP)	Conversationnel, opt-out
statuses	Statut d'un message envoyé (sent, delivered, read, failed)	DLR / tracking
errors	Erreur sur un envoi	Alertes, retry
phone_number_quality_update	Changement de quality rating	Monitoring délivrabilité
phone_number_name_update	Statut du display name	Onboarding
template_status_update	Approbation/rejet d'un template	Gestion templates
account_update	Modifications du WABA	Admin

Les événements messages et statuses sont les plus critiques pour les opérations quotidiennes. Un événement statuses avec le champ status: "read" indique que le destinataire a lu le message — une information qui n'existe pas en SMS.

Configuration et sécurisation du webhook endpoint

La configuration se fait dans le Meta Business Manager ou via l'API Graph. Chaque WABA client doit pointer vers votre endpoint webhook. Côté technique :

• URL HTTPS uniquement. Meta rejette les endpoints HTTP. Le certificat TLS doit être signé par une autorité reconnue.
• Verification token. Lors de l'enregistrement du webhook, Meta appelle votre endpoint avec un challenge GET pour vérifier qu'il vous appartient. Votre endpoint doit retourner le challenge pour confirmer.
• Signature HMAC-SHA256. Chaque notification webhook est signée avec votre App Secret Meta. Vérifiez systématiquement la signature dans le header X-Hub-Signature-256 avant de traiter le payload. Ne pas vérifier la signature expose votre plateforme aux injections de faux événements.
• Répondre 200 rapidement. Meta attend un statut HTTP 200 dans les 20 secondes. Si votre endpoint tarde, Meta retente et peut désabonner le webhook après trop d'échecs. Le pattern recommandé : accuser réception (200) immédiatement, puis traiter l'événement de façon asynchrone dans une queue.

Architecture webhook pour une plateforme SMS multi-clients

Le point de complexité majeur pour une plateforme SMS est le routage des événements vers le bon client/tenant :

Webhook unique vs. webhook par client. Meta permet de configurer un seul endpoint webhook pour toute votre application, ce qui signifie que vous recevrez les événements de tous vos clients sur un seul endpoint. C'est l'architecture recommandée pour une plateforme multi-tenant : plus simple à maintenir qu'un endpoint par client.

Routage par waba_id ou phone_number_id. Chaque payload webhook contient l'identifiant du compte WABA et du numéro concerné. Utilisez ces identifiants pour router l'événement vers le bon tenant dans votre base de données.

Queue d'ingestion avec idempotence. Meta peut envoyer le même événement plusieurs fois (au moins une fois). Votre pipeline d'ingestion doit dédupliquer les événements par message_id pour éviter les doubles traitements (ex. : double crédit d'un DLR, double opt-out).

Scalabilité. En période de forte charge (campagne massive), le volume de webhooks statuses peut être considérable : chaque message envoyé génère jusqu'à 3 événements (sent, delivered, read). Dimensionnez votre endpoint et votre queue en conséquence.

Pour une référence complète sur la configuration des webhooks WhatsApp, consultez notre article webhooks WhatsApp API : configuration et réception.

Cas d'usage opérationnels pour les plateformes SMS

Les webhooks ouvrent des fonctionnalités distinctives par rapport au SMS :

• Read receipts dans les rapports de campagne. Afficher le taux de lecture (messages "read") en plus du taux de délivrance. C'est un argument commercial fort vis-à-vis du SMS qui n'a pas cet équivalent.
• Gestion des réponses conversationnelles. Un contact qui répond à un message WhatsApp déclenche un événement messages. Votre plateforme peut router cette réponse vers une boîte de réception unifiée, un chatbot, ou un agent humain.
• Opt-out automatique. Détecter les mots-clés STOP dans les messages entrants et déclencher la désinscription automatique dans la liste de contacts, sans intervention humaine.
• Alertes quality rating. L'événement phone_number_quality_update permet d'alerter le client en temps réel si son quality rating se dégrade, avant que le problème n'impacte ses campagnes.
• Suivi de templates. L'événement template_status_update notifie l'approbation ou le rejet d'un template par Meta, ce qui permet d'informer le client sans qu'il ait à surveiller le Business Manager.

FAQ

Faut-il un webhook endpoint différent pour chaque client de la plateforme SMS ?

Non, c'est même déconseillé. Un seul endpoint centralisé pour toute la plateforme simplifie l'architecture et la maintenance. Le routage vers les clients se fait en interne via les identifiants présents dans le payload webhook (waba_id, phone_number_id).

Que se passe-t-il si mon endpoint webhook est indisponible ?

Meta retente la livraison pendant 7 jours avec un backoff exponentiel. Si l'endpoint reste indisponible trop longtemps, Meta peut désabonner le webhook. À la reconnexion, les événements non livrés ne sont pas rejoués : il y aura un trou dans les données. Planifiez la haute disponibilité de votre endpoint webhook.

Les événements webhook sont-ils garantis dans l'ordre d'occurrence ?

Non. Meta ne garantit pas l'ordre des événements. Il est possible de recevoir un événement read avant l'événement delivered pour un même message. Votre logique de traitement doit être robuste à ce désordre (ex. : ne pas régresser un statut "read" en "delivered" si l'événement arrive en retard).

Peut-on filtrer les types d'événements reçus par webhook ?

Oui, partiellement. Lors de la configuration du webhook dans Meta Business Manager, vous pouvez cocher/décocher les champs (messages, statuses, etc.) auxquels vous souhaitez vous abonner. Cela permet de réduire le volume de notifications si vous n'avez pas besoin de tous les événements.

---

Les webhooks WhatsApp sont la colonne vertébrale du temps réel dans une plateforme SMS étendue à WhatsApp. Bien les implémenter, c'est offrir à vos clients des fonctionnalités (lecture, conversation, alertes) absentes du SMS. Whakup fournit l'infrastructure API REST et webhook avec hébergement EU. Explorez notre offre API WhatsApp Business et consultez notre guide complet API WhatsApp Business pour l'ensemble de l'architecture.