API WhatsApp et les webhooks : guide pour les SaaS e-commerce

Les webhooks de l'API WhatsApp Business sont le mécanisme par lequel Meta notifie votre SaaS de tout événement lié à un numéro ou un WABA : message reçu, statut de livraison mis à jour, quality rating modifié, template approuvé. Pour un SaaS e-commerce, les webhooks sont le moteur des scénarios temps réel — confirmation de commande, alerte de livraison, réponse à un message client, déclenchement de bot conversationnel. Sans webhooks bien configurés, l'API WhatsApp n'est qu'un canal d'envoi unidirectionnel.

Les événements webhook essentiels pour l'e-commerce

L'API WhatsApp Business envoie des notifications dans deux grandes catégories d'objets : messages et statuses. Chaque événement est reçu sur votre endpoint en HTTP POST avec un payload JSON.

Événements messages (messages entrants)

Type	Déclencheur	Usage e-commerce
text	Message texte reçu	Commandes par mot-clé, questions au service client
interactive	Clic sur un bouton ou sélection dans une liste	Confirmation de commande, choix de livraison
order	Envoi d'une commande depuis un catalogue WhatsApp	Commande directe depuis le chat
image, document	Pièce jointe reçue	Preuve de retour, photo de produit endommagé
reaction	Réaction emoji sur un message	Signal d'engagement

Événements statuses (statuts de livraison)

Statut	Signification	Action recommandée
sent	Message accepté par Meta	Log interne
delivered	Message délivré sur le téléphone du destinataire	Mise à jour du statut dans le CRM/commande
read	Message lu par le destinataire	Trigger d'un follow-up si pas de réponse sous X heures
failed	Échec d'envoi	Alerte, tentative de fallback (SMS, email)

Configuration technique du webhook

Étape 1 : déclarer l'endpoint dans le Business Manager Meta

Votre endpoint doit être accessible publiquement en HTTPS. Meta effectue une vérification initiale en envoyant un GET avec un token de challenge :

GET https://votre-saas.com/webhooks/whatsapp
  ?hub.mode=subscribe
  &hub.challenge=1234567890
  &hub.verify_token=VOTRE_TOKEN_SECRET

Votre endpoint doit retourner la valeur exacte de hub.challenge avec un code HTTP 200.

Étape 2 : traiter les notifications POST

Une fois l'endpoint vérifié, Meta envoie les événements en POST. Structure de base d'un payload de message entrant :

{
  "entry": [{
    "id": "WABA_ID",
    "changes": [{
      "value": {
        "messaging_product": "whatsapp",
        "metadata": { "phone_number_id": "NUMERO_ID" },
        "messages": [{
          "from": "336XXXXXXXX",
          "id": "wamid.XXXXX",
          "type": "text",
          "text": { "body": "Où est ma commande ?" }
        }]
      }
    }]
  }]
}

Étape 3 : acquittement et traitement asynchrone

Votre endpoint doit retourner un HTTP 200 dans les 5 secondes après réception du webhook. Si Meta ne reçoit pas de 200 dans ce délai, il retentera la livraison jusqu'à 10 fois sur 24 heures.

Ne traitez jamais la logique métier de façon synchrone dans le handler webhook. La bonne pratique est :

1. Recevoir le POST, vérifier la signature HMAC
2. Pousser le payload dans une queue interne (Redis, SQS)
3. Retourner 200 immédiatement
4. Traiter la logique métier depuis un worker asynchrone

Étape 4 : vérifier la signature HMAC

Meta signe chaque payload avec votre App Secret via HMAC-SHA256. Le hash est envoyé dans l'en-tête X-Hub-Signature-256. Vérifiez cette signature avant tout traitement pour éviter les injections malveillantes.

import hmac, hashlib

def verify_signature(payload_body: bytes, signature: str, app_secret: str) -> bool:
    expected = "sha256=" + hmac.new(
        app_secret.encode(), payload_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

Scénarios e-commerce activés par les webhooks

Confirmation de commande interactive

1. Votre SaaS envoie un template "Confirmez votre commande #12345" avec des boutons Oui / Non
2. Le webhook interactive déclenche la confirmation ou l'annulation dans votre système de commandes
3. Une notification de confirmation est envoyée automatiquement

Alerte de livraison avec suivi en temps réel

1. Votre système de gestion logistique déclenche un événement "colis expédié"
2. Votre SaaS envoie un template utility avec lien de tracking
3. Le webhook read confirme que le client a pris connaissance de l'information
4. Si failed, le SaaS bascule automatiquement sur un SMS de secours

Bot de support post-achat

1. Le client envoie "retour" ou "remboursement" — événement text reçu via webhook
2. Votre bot NLU interprète l'intention
3. Le SaaS envoie une liste interactive des commandes récentes pour sélection
4. Le webhook interactive capture la sélection et ouvre automatiquement un ticket de retour

FAQ

L'ordre de livraison des webhooks est-il garanti ?

Non. Meta ne garantit pas l'ordre des événements. Un événement read peut arriver avant l'événement delivered correspondant. Votre code doit gérer les arrivées dans le désordre, notamment en utilisant les wamid (identifiants de message) pour réconcilier les statuts.

Que faire si un webhook n'est pas reçu (perte de message) ?

Meta retentera la livraison jusqu'à 24 heures en cas d'échec. Pour les événements critiques (paiement, commande), complétez les webhooks avec une réconciliation périodique via l'API Graph en interrogeant l'état des messages récents. N'architecture jamais un processus de paiement qui dépend exclusivement des webhooks sans mécanisme de vérification.

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

Oui. Lors de la configuration du webhook dans le Business Manager ou via l'API, vous sélectionnez les champs souscrits (messages, message_status_updates, phone_number_quality_updates, etc.). Souscrivez uniquement aux événements dont vous avez besoin pour limiter le volume de trafic entrant.

Comment gérer les duplications de webhooks ?

Meta peut envoyer le même événement plusieurs fois (at-least-once delivery). Implémentez un mécanisme d'idempotence basé sur le wamid : stockez les identifiants de messages déjà traités dans un cache (Redis avec TTL de 24h) et ignorez les doublons.

---

Les webhooks sont le système nerveux de votre intégration WhatsApp e-commerce. Un endpoint robuste, asynchrone et idempotent est la différence entre une intégration qui tient en production et une qui génère des incidents à chaque pic de commandes.

Whakup fournit aux éditeurs de SaaS e-commerce une API WhatsApp Business avec webhooks fiabilisés, architecture multi-tenant et hébergement EU. Pour approfondir, consultez notre guide complet de l'API WhatsApp Business et notre article sur les templates WhatsApp et leurs catégories pour structurer vos notifications e-commerce.