API WhatsApp en Python/Flask : tutoriel serveur webhook

Recevoir et traiter les messages WhatsApp entrants demande un serveur webhook fiable, capable de répondre à Meta en moins de quelques secondes sous peine de voir les événements retentés voire perdus. Python et Flask offrent un excellent compromis pour construire ce type de service : léger, rapide à déployer et bien outillé. Ce tutoriel présente les étapes clés d'un webhook WhatsApp Cloud API en production, pensé pour les développeurs marocains qui intègrent la solution dans leurs SaaS ou back-offices e-commerce.

Architecture générale

Un webhook WhatsApp est un simple endpoint HTTPS que Meta appelle chaque fois qu'un événement survient : message entrant, statut de livraison, changement de profil client, etc. Le serveur doit répondre avec un code HTTP 200 très rapidement, puis traiter le contenu de manière asynchrone pour ne pas bloquer les appels suivants.

Les prérequis techniques

• Un serveur accessible en HTTPS avec un certificat valide (Let's Encrypt suffit).
• Un domaine ou sous-domaine dédié, idéalement derrière un reverse proxy Nginx.
• Une file de traitement asynchrone comme Celery ou RQ pour découpler la réception du traitement.
• Un système de logs structurés pour tracer chaque événement.

Configuration côté Meta Business Manager

Avant d'écrire une ligne de code, il faut déclarer l'URL du webhook dans le Meta Business Manager, section WhatsApp Configuration. Meta demande une vérification GET initiale avec un token secret défini par le développeur : le serveur doit renvoyer la valeur du paramètre hub.challenge si le token correspond.

La route de vérification en Flask

Cette route est appelée une seule fois lors de la configuration. Elle prend trois paramètres en query string : hub.mode, hub.verify_token et hub.challenge. La logique est simple : comparer le token reçu au token stocké côté serveur, et renvoyer le challenge en clair si tout est bon.

La route de réception des événements

Meta envoie tous les événements en POST JSON sur le même endpoint. Le corps de la requête contient un objet entry avec un tableau de changes, chacun pouvant contenir plusieurs messages ou statuts.

Vérification de la signature HMAC

Meta signe chaque requête avec l'en-tête X-Hub-Signature-256. Le serveur doit calculer un HMAC SHA-256 du corps brut avec l'App Secret comme clé, puis comparer le résultat à la signature reçue. Sans cette vérification, n'importe qui peut envoyer de faux événements.

Le parsing des messages

Le JSON WhatsApp est richement typé. Chaque message porte un type parmi text, image, audio, video, document, interactive, button, location, avec une structure différente selon le cas. Un dispatch propre par type facilite la maintenance et l'ajout de nouvelles fonctionnalités.

Envoi de réponses via l'API Cloud

Pour répondre à un message entrant, l'application appelle l'endpoint https://graph.facebook.com/v18.0/{PHONE_NUMBER_ID}/messages avec un token Bearer et un payload JSON. La bibliothèque requests suffit largement, mais pour la production on préférera httpx asynchrone.

Gestion des erreurs

• Code 400 : payload invalide, souvent un template non approuvé ou un paramètre manquant.
• Code 401 : token expiré ou révoqué, à renouveler dans le Business Manager.
• Code 429 : quota atteint, il faut implémenter un backoff exponentiel.
• Code 500 : erreur temporaire côté Meta, retry après quelques secondes.

Déploiement en production au Maroc

Pour héberger ce type de service, plusieurs options existent selon les contraintes de latence et de conformité :

• OVHcloud région Europe : latence estimée à 30-50 ms vers le Maroc, très bon compromis prix/performance.
• Scaleway Paris : profil similaire, avec une bonne intégration DevOps.
• Cloud local marocain (N+ONE, Genious Communications) : intéressant si le projet impose une localisation stricte des données, en cohérence avec la loi 09-08.

Sécurisation basique

En production, ajouter systématiquement : un pare-feu applicatif basique, un rate limiting par IP source, une rotation régulière des tokens Meta, et un stockage chiffré des messages sensibles (OTP, données bancaires) au repos.

Conclusion

Un webhook WhatsApp en Python/Flask peut passer d'un prototype fonctionnel à un service production-ready en quelques jours seulement, à condition de traiter dès le départ la sécurité (HMAC, HTTPS), l'asynchronisme (file de tâches) et l'observabilité (logs structurés). C'est un socle solide sur lequel viennent se greffer chatbots, OTP, notifications transactionnelles et intégrations métier plus larges.