API WhatsApp et les webhooks : guide pour les agences de communication

Les webhooks WhatsApp sont le mécanisme par lequel l'API WhatsApp Business notifie votre système en temps réel de tout événement survenu sur un numéro : message reçu d'un utilisateur, statut de livraison d'un message envoyé, changement de qualité du numéro, mise à jour d'un template. Pour une agence de communication qui gère les présences WhatsApp de ses clients, maîtriser les webhooks est la condition pour construire des expériences client réactives — chatbots, notifications automatiques, escalade vers un agent humain — sans polling permanent de l'API.

Ce que les webhooks WhatsApp peuvent vous envoyer

Meta envoie les événements webhook vers une URL HTTPS que vous configurez sur votre Business App. Les événements sont regroupés en plusieurs catégories.

Événements messages (les plus utilisés) :

• messages : un utilisateur vous envoie un message (texte, image, document, réaction, localisation...).
• message_status : statut d'un message que vous avez envoyé (sent, delivered, read, failed).
• message_template_status_update : un template que vous avez soumis vient d'être approuvé ou rejeté.

Événements compte :

• phone_number_quality_update : le quality rating d'un numéro change (High → Medium → Low ou inversement).
• phone_number_name_update : le nom affiché du numéro est mis à jour.
• account_update : changement sur le WABA (statut du compte, permissions modifiées).
• account_review_update : résultat d'une révision de compte par Meta.

Structure typique d'un payload webhook :

{
  "object": "whatsapp_business_account",
  "entry": [{
    "id": "WABA_ID",
    "changes": [{
      "value": {
        "messaging_product": "whatsapp",
        "metadata": {
          "display_phone_number": "33600000000",
          "phone_number_id": "PHONE_NUMBER_ID"
        },
        "messages": [{
          "from": "33611111111",
          "id": "wamid.xxx",
          "timestamp": "1720000000",
          "type": "text",
          "text": { "body": "Bonjour" }
        }]
      },
      "field": "messages"
    }]
  }]
}

Le phone_number_id présent dans chaque payload est votre clé de routage dans une architecture multi-client. C'est lui qui vous permet de savoir à quel client appartient l'événement reçu.

Configuration et sécurisation de votre endpoint webhook

Configuration dans le Meta Developer Dashboard :

1. Accédez à votre Business App > Produit WhatsApp > Configuration.
2. Renseignez l'URL de votre webhook (doit être HTTPS, certificat valide).
3. Définissez un "verify token" (chaîne arbitraire secrète que Meta vous renverra lors de la vérification).
4. Meta envoie une requête GET avec hub.challenge et hub.verify_token — votre endpoint doit retourner hub.challenge si le token correspond.
5. Sélectionnez les champs auxquels vous souhaitez vous abonner (messages, message_status, etc.).

Sécurisation des appels entrants : Chaque requête webhook de Meta inclut un header X-Hub-Signature-256 contenant un HMAC-SHA256 du payload signé avec le "App Secret" de votre Business App. Vérifiez systématiquement cette signature avant de traiter le payload.

HMAC-SHA256(app_secret, raw_body) == X-Hub-Signature-256 header value

Ne traitez jamais un webhook sans vérification de signature — cela exposerait votre endpoint à des injections de faux événements.

Bonnes pratiques de résilience :

• Répondez 200 OK à Meta immédiatement, avant de traiter le payload. Si votre endpoint tarde à répondre, Meta considère l'envoi comme échoué et retente.
• Traitez les événements de manière asynchrone (file de messages interne).
• Gérez l'idempotence : Meta peut envoyer le même événement plusieurs fois. Utilisez l'identifiant du message (wamid) comme clé de déduplication.

Pour comprendre l'architecture globale de l'API dans laquelle s'inscrivent ces webhooks, consultez notre guide complet de l'API WhatsApp Business.

Cas d'usage webhooks pour les agences de communication

Les webhooks ouvrent des possibilités concrètes pour les clients d'une agence de communication.

Chatbot et réponses automatiques : À réception d'un message entrant (messages), votre système analyse le contenu et répond automatiquement selon un arbre de décision ou via un moteur NLP. La latence perçue par l'utilisateur dépend directement de votre temps de traitement webhook — visez moins de 2 secondes entre réception et réponse.

Suivi de livraison des campagnes : Les événements message_status (delivered, read) vous permettent de calculer des taux de délivrabilité et de lecture en temps réel. Exposez ces métriques dans vos rapports de campagne — les clients WhatsApp attendent un niveau de détail bien supérieur à l'email.

Statut	Signification
sent	Message transmis aux serveurs Meta
delivered	Message reçu sur le téléphone du destinataire
read	Message ouvert par le destinataire
failed	Erreur de livraison (numéro invalide, bloqué, rate limit)

Escalade vers agent humain : Quand un utilisateur envoie un message indiquant un problème (mots-clés détectés, sentiment négatif, demande explicite d'un conseiller), déclenchez automatiquement une notification à un agent humain via votre CRM ou votre outil de ticketing. Le webhook messages est le déclencheur.

Alertes quality rating : Abonnez-vous au webhook phone_number_quality_update et configurez une alerte immédiate (email, Slack) quand le quality rating d'un numéro client passe en "Medium" ou "Low". Agir dès le "Medium" évite d'atteindre la suspension.

L'API WhatsApp de Whakup est construite autour d'une architecture webhooks fiable, avec retry automatique, signature vérifiée et logs d'événements consultables via l'interface partenaire.

Architecture recommandée pour une agence gérant plusieurs clients

Une agence qui gère 10, 20 ou 50 comptes clients sur WhatsApp fait face à un problème de routage : tous les webhooks arrivent sur la même URL configurée dans votre Business App (ou sur des URLs différentes si vous avez une app par client, ce qui est peu scalable).

Architecture centralisée recommandée :

Meta Webhooks → Endpoint unique (votre API)
                  ↓
        Extraction du phone_number_id
                  ↓
        Lookup table (phone_number_id → client_id)
                  ↓
        File de messages par client (Redis / SQS)
                  ↓
        Workers de traitement par client

Cette architecture vous permet de :

• Gérer les pics de volume (un client envoie une campagne → flood de statuts de livraison) sans impacter les autres clients.
• Tracer les événements par client pour votre facturation et vos rapports.
• Ajouter des clients sans modifier la configuration webhook Meta.

Pour une agence qui souhaite passer d'une intégration ponctuelle à une offre WhatsApp structurée, notre analyse build vs buy WhatsApp API aide à évaluer ce qu'il est pertinent de développer en interne versus de déléguer à un partenaire.

FAQ

À quelle fréquence Meta retente l'envoi d'un webhook en cas d'échec ?

Meta retente l'envoi selon une politique de backoff exponentiel si votre endpoint retourne une erreur ou ne répond pas dans le délai imparti. Les retentatives peuvent s'étaler sur plusieurs heures. Après un certain nombre d'échecs consécutifs, Meta peut désactiver le webhook. Assurez une disponibilité maximale de votre endpoint (SLA 99,9%+) et monitorizez les erreurs de webhook dans votre Business Manager.

Peut-on filtrer les événements webhook pour ne recevoir que certains types ?

Oui. Lors de la configuration dans le Meta Developer Dashboard, vous sélectionnez les "champs" auxquels vous vous abonnez. Vous pouvez choisir uniquement messages si vous n'avez pas besoin des mises à jour de quality rating, par exemple. Cela réduit le volume de requêtes entrantes et simplifie votre logique de traitement.

Les webhooks fonctionnent-ils en mode sandbox (environnement de test) ?

Oui. L'environnement de test Meta envoie des webhooks réels vers votre endpoint configuré. Vous pouvez utiliser un outil comme ngrok pour exposer un endpoint local pendant vos tests. Assurez-vous d'utiliser un verify token différent entre votre environnement de test et votre environnement de production.

Comment gérer les messages WhatsApp qui arrivent hors des heures de bureau ?

Le webhook reçoit les messages 24/7. La gestion des plages horaires est entièrement à votre charge applicative. Deux approches : stocker les messages entrants hors horaires dans une file d'attente pour traitement humain le lendemain matin, ou activer un bot de réponse automatique ("Nous vous répondons dans les 24h") pour les messages reçus hors plage. L'implémentation repose sur votre logique applicative, pas sur une fonctionnalité Meta native.

---

Les webhooks WhatsApp sont le système nerveux de toute intégration réactive. Bien implémentés, ils transforment WhatsApp en canal de communication bidirectionnel en temps réel, bien au-delà de la simple diffusion de messages. Whakup fournit à ses partenaires une infrastructure webhook fiable, avec logs et retry management intégrés. Découvrez notre offre API WhatsApp pour agences et intégrateurs.