Webhooks WhatsApp Cloud API : guide développeur

Les webhooks WhatsApp Cloud API sont le pont temps réel entre Meta et votre application. Sans eux, impossible de recevoir un message entrant, de connaître le statut d'un envoi ou de réagir à une mise à jour de template. Guide technique complet pour les développeurs marocains qui intègrent la WhatsApp Business API.

Comprendre l'architecture des webhooks

Un webhook est un endpoint HTTPS exposé par votre backend, que Meta appelle en POST à chaque événement pertinent. Contrairement à un polling, la réactivité est immédiate : le message entrant arrive typiquement en moins de 500 ms sur votre serveur.

Meta envoie une notification en JSON structurée, signée avec un HMAC SHA-256 basé sur votre App Secret. La validation de cette signature est obligatoire pour éviter les injections malveillantes.

Configuration initiale

1. Créez une App Meta dans le tableau de bord Meta for Developers.
2. Ajoutez le produit WhatsApp et configurez le numéro de test ou de production.
3. Dans la section Webhooks, renseignez votre URL HTTPS et un Verify Token secret que vous choisissez.
4. Meta effectue un GET de vérification avec les paramètres hub.mode, hub.verify_token et hub.challenge. Votre endpoint doit renvoyer le challenge tel quel avec un HTTP 200.
5. Abonnez-vous aux fields qui vous intéressent : messages, message_status, message_template_status_update, etc.

Les principaux événements à gérer

Message entrant

Un client envoie un message texte, image, audio ou interactif. Le payload contient l'ID du message, le numéro d'expéditeur, le type et le contenu. Répondez en HTTP 200 en moins de 20 secondes pour éviter les retries.

Statut de message sortant

Quatre statuts successifs : sent (parti du serveur Meta), delivered (reçu par le téléphone), read (lu par l'utilisateur si les accusés sont activés), failed (échec, avec code d'erreur détaillé).

Mise à jour de template

Approbation, rejet ou pause d'un template par Meta. Utile pour alerter votre équipe et corriger rapidement un template rejeté.

Sécurité : validation HMAC obligatoire

À chaque POST, Meta ajoute un header X-Hub-Signature-256 contenant la signature HMAC. Votre code doit recalculer la signature avec l'App Secret et refuser toute requête où les deux ne correspondent pas.

Exemple Node.js

En Express, on utilise crypto.createHmac('sha256', APP_SECRET) sur le body brut, puis on compare avec crypto.timingSafeEqual pour éviter les attaques temporelles. Attention à conserver le body brut avant tout parsing JSON, sinon la signature ne correspondra jamais.

Gestion des retries et de l'idempotence

Si votre endpoint renvoie une erreur ou dépasse 20 secondes, Meta rejoue la requête avec un backoff exponentiel pendant environ 7 jours. Deux règles d'or :

• Idempotence : utilisez l'ID de message pour dédupliquer, ne traitez chaque message qu'une fois.
• Réponse rapide : accusez réception en HTTP 200 immédiatement puis traitez en asynchrone (queue Redis, RabbitMQ, BullMQ).

Erreurs fréquentes en production

• Endpoint non HTTPS ou certificat auto-signé, refusé par Meta.
• Body parsé avant validation HMAC, cassant le calcul de signature.
• Timeouts trop longs sur les traitements synchrones (envoi email, appel base de données lente).
• Absence de logs structurés : quand un message manque, impossible de savoir si le webhook n'a pas été reçu ou si le traitement a échoué.

Monitoring et observabilité

Instrumentez vos webhooks avec des métriques précises : latence P50/P95, taux d'erreur, volume par type d'événement. Un simple dashboard Grafana ou Datadog suffit à détecter une dégradation avant qu'elle n'impacte vos clients marocains.

Conclusion

Les webhooks WhatsApp Cloud API sont robustes mais exigent une hygiène technique stricte : validation HMAC, idempotence, traitement asynchrone et monitoring. Ces quatre disciplines transforment votre intégration d'un prototype fragile en une brique de production capable de traiter des millions de messages pour vos clients au Maroc et ailleurs.