API WhatsApp et les webhooks : guide pour les plateformes de fidélité

Les webhooks WhatsApp API sont le mécanisme qui permet à votre plateforme de fidélité de réagir en temps réel aux actions de vos clients finaux : un message entrant, une réponse à une campagne, un clic sur un bouton interactif, ou une mise à jour du statut de livraison d'un message. Sans webhooks correctement configurés, votre plateforme envoie dans le vide et ne peut pas mesurer ni agir sur l'engagement de vos membres.

Ce qu'est un webhook WhatsApp API

Un webhook est une URL HTTPS que vous déclarez à Meta. Dès qu'un événement se produit sur votre numéro WhatsApp Business (message reçu, statut d'un message envoyé, changement de quality rating…), Meta envoie une requête HTTP POST à cette URL avec un payload JSON décrivant l'événement.

Contrairement à un polling (interrogation périodique de l'API), les webhooks sont push : Meta vous envoie l'information au moment où elle se produit, sans délai. Pour une plateforme de fidélité, c'est la condition pour :

• Créditer des points en temps réel quand un membre répond à une offre.
• Déclencher un flux conversationnel immédiatement après qu'un client a scanné un QR code.
• Mesurer le taux de lecture et de réponse de chaque campagne.
• Gérer les opt-out instantanément pour rester conforme.

Configuration technique des webhooks

Prérequis :

• Une URL HTTPS publique, accessible depuis internet (pas localhost).
• Un certificat SSL valide (auto-signé refusé par Meta).
• Un endpoint capable de répondre en moins de 20 secondes avec un code HTTP 200.

Les deux étapes de configuration :

1. Vérification de l'URL (challenge) : lors de l'abonnement, Meta envoie une requête GET avec un paramètre hub.verify_token que vous avez défini et un hub.challenge. Votre endpoint doit vérifier le token et retourner le hub.challenge en texte brut pour valider l'URL.

2. Abonnement aux champs : une fois l'URL vérifiée, vous vous abonnez aux champs d'événements qui vous intéressent via l'API ou le Business Manager.

// Exemple de validation du webhook (Node.js)
app.get('/webhook/whatsapp', (req, res) => {
  const mode = req.query['hub.mode'];
  const token = req.query['hub.verify_token'];
  const challenge = req.query['hub.challenge'];
  
  if (mode === 'subscribe' && token === process.env.WEBHOOK_VERIFY_TOKEN) {
    res.status(200).send(challenge);
  } else {
    res.sendStatus(403);
  }
});

Champs d'abonnement recommandés pour une plateforme de fidélité :

Champ webhook	Événement délenché	Usage fidélité
messages	Message reçu d'un client	Réponse à une offre, question support
message_deliveries	Message délivré au téléphone	Confirmation délivrabilité
message_reads	Message lu par le client	Taux d'ouverture des campagnes
message_reactions	Réaction emoji à un message	Engagement sur les offres
phone_number_quality_update	Changement du quality rating	Monitoring délivrabilité
phone_number_name_update	Changement du display name	Alertes administratives

Traiter les événements de fidélité en temps réel

Pour une plateforme de fidélité, les événements les plus critiques sont les messages entrants (messages) et les statuts de livraison (message_deliveries, message_reads).

Traitement des messages entrants :

Un payload de message entrant ressemble à ceci :

{
  "entry": [{
    "changes": [{
      "value": {
        "messages": [{
          "from": "33612345678",
          "type": "text",
          "text": {"body": "J'utilise le code PROMO10"},
          "timestamp": "1720350000"
        }]
      }
    }]
  }]
}

Votre plateforme doit :

1. Identifier le membre par son numéro (from).
2. Parser le contenu du message pour détecter les mots-clés (code promo, "OUI", "STOP"…).
3. Déclencher l'action correspondante (crédit de points, activation d'une offre, opt-out).
4. Répondre immédiatement si une réponse est attendue.

Importance de répondre en moins de 20 secondes : si votre endpoint met plus de 20 secondes à répondre avec un 200, Meta considère le webhook comme défaillant et met en place un mécanisme de retry. Après plusieurs échecs, Meta peut désabonner votre URL. Ne jamais traiter la logique métier dans le handler du webhook — accusez réception avec un 200 immédiat et traitez l'événement de manière asynchrone via une queue.

Architecture recommandée pour une plateforme de fidélité

Une architecture robuste pour les webhooks WhatsApp dans une plateforme de fidélité se structure ainsi :

Meta → POST /webhook → Endpoint (répond 200 immédiatement)
                         ↓
                    Queue (Redis, SQS, RabbitMQ)
                         ↓
                    Worker (traitement asynchrone)
                         ↓
              Logique métier (points, offres, segmentation)
                         ↓
              API WhatsApp (réponse si nécessaire)

Cette architecture découple la réception de l'événement de son traitement. Elle permet de :

• Absorber les pics de messages (campagnes qui génèrent de nombreuses réponses simultanées).
• Retenter le traitement en cas d'erreur sans perdre d'événements.
• Monitorer le volume d'événements et détecter les anomalies.

L'API WhatsApp Whakup fournit une infrastructure webhook multi-tenant où chaque numéro peut avoir sa propre URL de callback, ce qui simplifie l'isolation des événements par compte client dans votre plateforme de fidélité.

Pour comprendre comment les webhooks s'articulent avec les templates de campagnes, consultez notre guide sur les templates WhatsApp et leurs catégories et notre guide complet de l'API WhatsApp Business.

FAQ

Meta renvoie-t-il les événements si mon serveur est temporairement hors ligne ?

Oui, Meta implémente un mécanisme de retry avec backoff exponentiel pendant environ 7 jours. Mais les événements ne sont pas garantis : si votre endpoint reste indisponible trop longtemps, certains événements peuvent être perdus. Il faut viser une haute disponibilité (99,9%+) pour les endpoints webhook en production.

Peut-on avoir plusieurs URLs webhook pour un même numéro WhatsApp ?

Non, Meta ne supporte qu'une URL webhook par application (app_id). Si votre plateforme gère plusieurs clients avec le même app_id, tous les événements arrivent sur la même URL — c'est votre logique de routage qui doit les dispatcher vers le bon client en se basant sur le phone_number_id présent dans chaque payload.

Comment sécuriser les appels webhook reçus de Meta ?

Meta signe chaque requête webhook avec un HMAC-SHA256 utilisant votre app_secret. L'en-tête X-Hub-Signature-256 contient la signature. Votre endpoint doit vérifier cette signature avant de traiter le payload pour s'assurer que la requête vient bien de Meta.

Les webhooks fonctionnent-ils pour les messages WhatsApp Flows (formulaires interactifs) ?

Oui. Les soumissions de WhatsApp Flows génèrent un événement de type interactive dans le champ messages du webhook, avec un payload structuré contenant les réponses du formulaire. C'est le mécanisme recommandé pour collecter des données structurées (inscription au programme de fidélité, enquête de satisfaction) directement dans WhatsApp.

---

Les webhooks sont le système nerveux de votre intégration WhatsApp : sans eux, votre plateforme de fidélité ne peut pas écouter, mesurer ni agir. Configurez-les dès le début, avec une architecture asynchrone solide. Accédez à l'API WhatsApp via Whakup pour une infrastructure webhook multi-tenant prête à l'emploi, hébergée en EU.