Webhooks WhatsApp API : Configurer et Recevoir les Événements en Temps Réel

Les webhooks sont le système nerveux de votre intégration WhatsApp API. Sans eux, vous envoyez des messages dans le vide — vous ne savez pas s'ils sont arrivés, lus, ou si quelqu'un a répondu. Ce guide vous explique comment configurer vos webhooks WhatsApp de A à Z, avec des exemples de code concrets pour traiter chaque type d'événement.

Comprendre le Fonctionnement des Webhooks WhatsApp

Un webhook est une URL de votre serveur que Meta appelle automatiquement chaque fois qu'un événement se produit sur votre numéro WhatsApp. Meta envoie une requête HTTP POST avec un payload JSON décrivant l'événement — à vous de le traiter selon votre logique métier.

Les événements WhatsApp se répartissent en plusieurs catégories principales :

Événements de statut de message (message_status)

• sent : le message a été transmis aux serveurs WhatsApp
• delivered : le message a été livré sur l'appareil du destinataire
• read : le destinataire a ouvert et lu le message
• failed : l'envoi a échoué (numéro invalide, utilisateur non WhatsApp, etc.)

Événements de message entrant

• text : message texte simple
• image, video, audio, document : médias reçus
• interactive : réponse à un bouton ou à une liste
• button : clic sur un bouton de template

Événements système

• Mise à jour du profil utilisateur
• Blocage/déblocage par un contact

Cette granularité vous permet de construire des expériences utilisateur sophistiquées : relance automatique si le message n'est pas lu, qualification des leads selon leurs réponses, intégration CRM en temps réel.

Prérequis Techniques pour vos Webhooks

Avant de configurer vos webhooks dans le Meta Developer Dashboard, votre endpoint doit respecter plusieurs contraintes :

HTTPS obligatoire : Meta ne supporte pas les URL HTTP en clair. Votre serveur doit avoir un certificat SSL valide (pas un certificat auto-signé).

Accessibilité publique : L'URL doit être accessible depuis Internet. Un serveur local (localhost) ne fonctionne pas en production. Pour le développement, vous pouvez utiliser ngrok ou Cloudflare Tunnel pour exposer temporairement un serveur local.

Réponse rapide : Meta attend une réponse 200 OK de votre webhook dans un délai de 20 secondes. Si votre traitement prend plus longtemps, répondez 200 immédiatement et traitez l'événement en arrière-plan (queue de messages).

Vérification du token : Lors de l'enregistrement, Meta effectue une requête GET avec un challenge. Votre serveur doit retourner ce challenge pour confirmer que vous contrôlez l'URL.

Configuration Technique des Webhooks

Voici un exemple d'implémentation en Node.js (Express) pour recevoir les webhooks WhatsApp :

const express = require('express');
const app = express();
app.use(express.json());

const VERIFY_TOKEN = process.env.WHATSAPP_VERIFY_TOKEN;

// Vérification initiale du webhook (GET)
app.get('/webhook', (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 === VERIFY_TOKEN) {
    console.log('Webhook vérifié avec succès');
    return res.status(200).send(challenge);
  }
  res.sendStatus(403);
});

// Réception des événements (POST)
app.post('/webhook', (req, res) => {
  // Répondre immédiatement 200 OK
  res.sendStatus(200);

  const body = req.body;
  if (body.object !== 'whatsapp_business_account') return;

  body.entry?.forEach(entry => {
    entry.changes?.forEach(change => {
      const value = change.value;

      // Traitement des messages entrants
      if (value.messages) {
        value.messages.forEach(message => {
          handleIncomingMessage(message, value.metadata);
        });
      }

      // Traitement des statuts
      if (value.statuses) {
        value.statuses.forEach(status => {
          handleStatusUpdate(status);
        });
      }
    });
  });
});

function handleIncomingMessage(message, metadata) {
  const from = message.from; // Numéro expéditeur
  const msgType = message.type;

  if (msgType === 'text') {
    console.log(`Message de ${from}: ${message.text.body}`);
    // Déclencher votre logique métier ici
  }

  if (msgType === 'interactive') {
    const reply = message.interactive.button_reply || message.interactive.list_reply;
    console.log(`Réponse bouton de ${from}: ${reply.id} - ${reply.title}`);
  }
}

function handleStatusUpdate(status) {
  console.log(`Message ${status.id}: statut ${status.status}`);
  // Mettre à jour votre base de données
}

app.listen(3000, () => console.log('Webhook server en écoute sur le port 3000'));

Configuration dans Meta Developer Dashboard :

1. Accédez à developers.facebook.com
2. Sélectionnez votre application > WhatsApp > Configuration
3. Dans la section "Webhooks", cliquez sur "Modifier"
4. Renseignez votre URL de webhook (ex: https://api.votredomaine.com/webhook)
5. Définissez un Verify Token (chaîne aléatoire sécurisée de votre choix)
6. Cliquez sur "Vérifier et enregistrer"
7. Souscrivez aux champs souhaités : messages, message_deliveries, message_reads

Sécuriser vos Webhooks : Validation de Signature

Meta signe chaque requête webhook avec une signature HMAC-SHA256 basée sur votre App Secret. Validez toujours cette signature pour vous assurer que la requête vient bien de Meta :

const crypto = require('crypto');

function validateWebhookSignature(req) {
  const signature = req.headers['x-hub-signature-256'];
  if (!signature) return false;

  const expectedSignature = 'sha256=' + crypto
    .createHmac('sha256', process.env.META_APP_SECRET)
    .update(JSON.stringify(req.body))
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

app.post('/webhook', (req, res) => {
  if (!validateWebhookSignature(req)) {
    return res.sendStatus(401); // Signature invalide
  }
  res.sendStatus(200);
  // Traitement...
});

Ne sautez pas cette étape en production — sans validation de signature, n'importe qui peut envoyer des fausses requêtes à votre webhook.

Gestion des Erreurs et Retry Logic

Meta retry les webhooks qui retournent une réponse non-200 ou qui ne répondent pas dans le délai imparti. La logique de retry suit une progression exponentielle : 1 min, 2 min, 4 min, 8 min, jusqu'à 16 tentatives. Après quoi, l'événement est perdu.

Pour éviter la perte d'événements, adoptez ce pattern robuste : répondez 200 immédiatement, puis publiez l'événement dans une file de messages (Redis Pub/Sub, RabbitMQ, AWS SQS) pour traitement asynchrone. Votre worker consomme la file indépendamment.

Pour les tests et le développement, utilisez les outils de débogage webhook intégrés au Meta Developer Dashboard — ils vous permettent de rejouer des événements passés, idéal pour déboguer sans attendre de vrais messages.

Les webhooks s'intègrent naturellement avec les chatbots WhatsApp et les flows d'automatisation. Consultez notre guide WhatsApp Business API pour le contexte général.

FAQ — Webhooks WhatsApp API

Combien de webhooks peut-on configurer par application Meta ? Par défaut, vous pouvez configurer un seul endpoint webhook par application. Si vous avez besoin de plusieurs endpoints (par exemple, un par numéro ou par environnement), il est recommandé d'utiliser un webhook unique qui route les événements en interne selon la logique appropriée.

Les webhooks fonctionnent-ils en sandbox/test ? Oui. L'environnement sandbox WhatsApp envoie des webhooks réels à votre endpoint configuré. C'est l'un des avantages du sandbox : vous pouvez tester votre traitement d'événements sans risquer d'affecter de vrais utilisateurs.

Que se passe-t-il si mon serveur webhook est hors ligne ? Meta retry les webhooks selon sa politique de retry (jusqu'à 16 tentatives sur environ 72 heures). Passé ce délai, les événements sont définitivement perdus. Il est donc essentiel de maintenir une haute disponibilité de votre endpoint webhook.

Comment déboguer les webhooks en développement local ? Utilisez ngrok (ngrok http 3000) pour exposer votre serveur local sur une URL publique HTTPS. Entrez cette URL dans votre configuration webhook Meta. Ngrok affiche aussi les requêtes entrantes en temps réel, ce qui facilite le débogage.

---

Prêt à connecter votre système au flux d'événements WhatsApp en temps réel ? Créez votre compte Whakup et bénéficiez d'une infrastructure webhook gérée, sans configuration serveur de votre côté.