API WhatsApp et les webhooks : guide pour les agences push notifications

Les webhooks WhatsApp API sont les événements en temps réel que Meta envoie à votre endpoint HTTP chaque fois qu'un message est reçu, un statut de livraison est mis à jour, ou qu'un événement système survient sur votre compte. Pour une agence qui gère des plateformes de push notifications, les webhooks sont l'épine dorsale de toute logique de confirmation de livraison, de gestion des réponses et de pilotage de la qualité. Sans eux, vous opérez à l'aveugle.

Les types d'événements webhook WhatsApp

L'API WhatsApp Cloud envoie plusieurs catégories d'événements distincts. Chaque catégorie correspond à un champ object et un tableau entry dans le payload JSON.

Événements de statut de message (message status updates) :

Statut	Signification
sent	Message transmis aux serveurs Meta
delivered	Message délivré sur l'appareil du destinataire
read	Message lu par le destinataire
failed	Échec d'envoi (code erreur inclus)

Événements de messages entrants :

• text : message texte reçu
• image, document, audio, video : médias reçus
• interactive : réponse à un bouton ou une liste
• button : réponse à un template avec boutons
• order : commande passée via catalogue WhatsApp

Événements système :

• phone_number_quality_update : changement du quality rating
• message_template_status_update : template approuvé, rejeté ou désactivé
• security : révocation de token
• account_review_update : changement de statut du compte Business

Pour une agence push notifications, les statuts delivered, read et failed sont les plus critiques pour votre reporting de campagne. Les événements système sont critiques pour la stabilité opérationnelle de votre plateforme.

Architecture d'un endpoint webhook robuste

Recevoir des webhooks Meta requiert une infrastructure spécifique. Meta valide votre endpoint lors de la configuration et s'attend à un comportement précis.

La vérification initiale (challenge-response). Lors de l'enregistrement de votre webhook, Meta envoie un GET avec un paramètre hub.challenge. Votre endpoint doit répondre avec ce challenge en HTTP 200. Sans cette validation, Meta refuse l'enregistrement.

La réponse rapide obligatoire. Meta attend un HTTP 200 en moins de 20 secondes. Si votre endpoint met plus longtemps ou retourne une erreur, Meta considère l'événement comme non délivré et retente. Votre logique de traitement doit être asynchrone : recevoir, acquitter immédiatement (200), puis traiter en arrière-plan.

La déduplication. Meta peut envoyer le même événement plusieurs fois (au moins once delivery). Votre système doit gérer les doublons via un identifiant unique de message (wamid) côté base de données.

La signature HMAC. Chaque webhook est signé avec votre App Secret Meta via un header X-Hub-Signature-256. Validez cette signature avant tout traitement pour éviter les injections malveillantes.

Pattern d'architecture recommandé pour une plateforme push notifications :

1. Endpoint HTTP léger qui valide la signature HMAC et retourne 200 immédiatement
2. Publication du payload brut dans une file de messages (Kafka, RabbitMQ, SQS)
3. Workers qui consomment la file, déduplicent et mettent à jour la base de données
4. Bus d'événements interne qui notifie les services métier (rapports, alertes, automations)

Pour voir comment intégrer ces webhooks dans une architecture API complète, consultez notre guide de l'API WhatsApp Business.

Webhooks et push notifications : les cas d'usage spécifiques aux agences

Une agence qui opère une plateforme push notifications exploite les webhooks WhatsApp différemment d'une simple notification e-commerce.

Suivi de livraison en temps réel. Pour chaque campagne envoyée, votre tableau de bord doit afficher les taux de sent, delivered et read en quasi temps réel. Les webhooks alimentent ces métriques. Attention : WhatsApp ne garantit pas la réception du webhook read si le destinataire a désactivé les accusés de lecture.

Gestion des échecs d'envoi. Le webhook failed inclut un code d'erreur. Les codes les plus fréquents en contexte push notifications :

• 131026 : numéro invalide (nettoyage de liste à déclencher)
• 131047 : fenêtre de 24h expirée (template non approuvé utilisé hors fenêtre)
• 131051 : type de message non supporté
• 131049 : plafond de volume atteint (retry à planifier)

Automatiser le traitement de ces codes d'erreur évite les interventions manuelles et améliore la délivrabilité globale.

Automations basées sur les réponses. Si votre plateforme gère des séquences conversationnelles, les webhooks interactive et button déclenchent les étapes suivantes du workflow. Un contact qui clique sur "En savoir plus" dans un template déclenche automatiquement l'envoi du message d'information suivant.

Alertes opérationnelles. Le webhook phone_number_quality_update doit déclencher une alerte immédiate dans votre système de monitoring. Un passage en rouge sur un numéro en cours de campagne nécessite une intervention en moins de quelques minutes pour limiter les dégâts.

Pour comprendre comment les templates structurent le contenu de vos campagnes, lisez notre guide sur les templates WhatsApp et leurs catégories.

Fiabilité et monitoring de votre infrastructure webhook

La robustesse de votre endpoint webhook est aussi critique que celle de votre API d'envoi. Un webhook manqué est une donnée perdue.

Monitoring à mettre en place :

• Taux de réponse HTTP 200 de votre endpoint (doit être proche de 100%)
• Latence de réponse (doit rester sous 5 secondes)
• Taille de la file de traitement (détecte les ralentissements backend)
• Taux de doublons reçus et filtrés

Gestion des reprises Meta. Si votre endpoint retourne un non-200, Meta retente l'envoi selon un backoff exponentiel sur 72 heures. Votre base de données doit pouvoir absorber ces reprises sans incohérence.

Alertes de silence webhook. Si votre endpoint ne reçoit aucun événement pendant une période anormalement longue (exemple : aucun statut pendant 10 minutes sur une campagne active), c'est souvent le signe d'un problème d'enregistrement webhook ou d'une suspension de compte. Configurez une alerte proactive.

Accédez à l'infrastructure webhook de Whakup avec monitoring intégré, gestion des reprises et alertes automatiques. Notre API REST + webhooks est conçue pour les agences qui opèrent des volumes industriels de notifications.

FAQ

Peut-on enregistrer plusieurs endpoints webhook sur un même compte WhatsApp Business ?

Non. L'API WhatsApp Cloud ne supporte qu'un seul endpoint webhook par application Meta. Si vous gérez plusieurs clients depuis la même application, votre endpoint unique doit router les événements vers le bon client en se basant sur le phone_number_id inclus dans chaque payload.

Les webhooks WhatsApp sont-ils garantis en livraison ?

Meta garantit une délivrance "at least once" : en cas d'échec de votre endpoint, Meta retente pendant 72 heures. Cela signifie que votre système recevra forcément l'événement si votre endpoint est disponible, mais peut le recevoir plusieurs fois. La déduplication côté votre système est obligatoire.

Comment tester les webhooks en développement sans un serveur public ?

Utilisez un tunnel HTTPS local (ngrok, Cloudflare Tunnel) pour exposer votre serveur de développement local à Meta. L'URL de tunnel doit être en HTTPS valide. Meta ne supporte pas les endpoints HTTP non chiffrés ni les certificats auto-signés.

Quelle est la durée de conservation des événements webhook par Meta en cas d'indisponibilité ?

Meta conserve les événements non délivrés et retente pendant 72 heures. Au-delà, les événements sont perdus. Votre infrastructure webhook doit garantir un taux de disponibilité très élevé (99,9%+) pour ne pas perdre des données de statut critiques pour votre reporting.

---

Les webhooks WhatsApp sont le lien entre votre plateforme de push notifications et la réalité de livraison de chaque message. Les ignorer ou les mal gérer crée des angles morts dans vos rapports et des échecs silencieux dans vos automations. Whakup fournit une couche webhook stable, monitorée et documentée pour que vos agences puissent se concentrer sur la logique métier plutôt que sur l'infrastructure. Parlez à notre équipe pour évaluer votre architecture d'intégration.