· 5 min · TextMeFlow Team

Tester les webhooks de l'API WhatsApp en local avec ngrok

Vous voulez construire une nouvelle intégration WhatsApp — un bot, une connexion CRM, un flux de notifications — mais votre serveur tourne sur localhost. TextMeFlow ne peut rien y envoyer : les webhooks sont des requêtes POST sortantes de nos serveurs vers une URL accessible publiquement. Tant que votre code n'est pas sur un vrai serveur, il vous faut un tunnel. Cet article montre comment faire avec ngrok, sans laisser par erreur un endpoint à moitié terminé en production.

Pourquoi tester en local dès le départ

Vous pourriez attendre le déploiement de votre endpoint pour voir si le payload est correct, mais c'est lent : chaque modification demande un nouveau déploiement pour savoir si votre analyse JSON, votre vérification de signature et votre logique métier fonctionnent ensemble. Tester en local avec un vrai webhook en direct — plutôt qu'avec un payload de test bricolé à la main — permet de détecter des erreurs que vous ne verriez sinon qu'en production : des en-têtes inattendus, la forme exacte de from_name dans les messages de groupe, ou un message avec média comportant un champ file que vous n'aviez pas prévu.

Étape 1 : démarrer ngrok

Installez ngrok (brew install ngrok ou téléchargement depuis leur site) et lancez un tunnel vers le port sur lequel tourne votre serveur local :

ngrok http 3000

Ngrok vous donne une URL publique du type https://a1b2c3d4.ngrok-free.app qui redirige vers http://localhost:3000. Avec le forfait gratuit, cette URL change à chaque redémarrage — gardez-le en tête si vous répétez l'étape suivante plusieurs fois.

Étape 2 : configurer temporairement le webhook

Allez sur /admin/webhook et saisissez l'URL ngrok comme endpoint, par exemple https://a1b2c3d4.ngrok-free.app/webhooks/whatsapp. Dès que vous enregistrez, le secret du webhook s'affiche — copiez-le immédiatement, car il est ensuite masqué. Envoyez-vous un message WhatsApp de test sur votre numéro couplé et vérifiez que la requête arrive bien sur votre serveur local.

Considérez cette configuration ngrok comme jetable : dès que vous avez fini de tester, remettez l'endpoint sur votre véritable URL de production. Un tunnel ngrok oublié qui n'existe plus après le redémarrage d'un ordinateur portable est le moyen le plus rapide de perdre silencieusement tous les messages entrants.

Étape 3 : vérifier la signature, même en local

La tentation est grande de sauter la vérification HMAC « parce que ce n'est que du test local » — mais vous ne testez alors pas ce qui se passe réellement en production. Lisez le corps brut avant que tout middleware JSON n'y touche et vérifiez immédiatement X-TextMeFlow-Signature :

const crypto = require('crypto');
const express = require('express');
const app = express();

app.post('/webhooks/whatsapp', express.raw({ type: 'application/json' }), (req, res) => {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', process.env.TMF_WEBHOOK_SECRET)
    .update(req.body)
    .digest('hex');

  if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(req.headers['x-textmeflow-signature'] || ''))) {
    return res.sendStatus(401);
  }

  const payload = JSON.parse(req.body);
  console.log(payload);
  res.sendStatus(200);
});

app.listen(3000);

Plus de détails sur les en-têtes, la logique de nouvelles tentatives et la façon la plus sûre de comparer la signature figurent dans l'article sur les signatures webhook.

Étape 4 : utiliser l'inspecteur ngrok pour rejouer

L'interface web locale de ngrok, sur http://127.0.0.1:4040, journalise chaque requête entrante, en-têtes et corps compris. C'est pratique pour deux choses, sans devoir envoyer un nouveau message WhatsApp à chaque fois :

  • Consulter le payload exact envoyé par TextMeFlow, pour écrire votre code d'analyse en conséquence.
  • Rejouer la même requête (« Replay ») après avoir déployé un correctif sur votre serveur local, sans renvoyer de message.

Attention toutefois : un rejeu via l'inspecteur ngrok réutilise le même X-TextMeFlow-Event-Id. Si votre logique d'idempotence repose sur ce champ — ce que nous recommandons — votre propre code ignorera donc à juste titre le rejeu. Ce n'est pas un bug, c'est votre déduplication qui fonctionne.

Erreurs courantes

Le webhook reste « pending » ou échoue en boucle : vérifiez que votre endpoint renvoie un 2xx en moins de 10 secondes. Effectuez les traitements lourds (mettre à jour un CRM, appeler une API externe) après cette réponse, pas avant — sinon votre serveur local semble avoir expiré et vous obtenez des nouvelles tentatives inutiles, avec un backoff de 1 min, 5 min, 30 min, 2 h et 6 h.

Deuxième erreur classique : l'URL ngrok change à chaque redémarrage (forfait gratuit), alors que le secret du webhook reste identique tant que vous ne recréez pas l'endpoint. Si vous mettez à jour l'URL dans /admin/webhook mais que votre .env local contient encore l'ancien secret, vous obtiendrez des 401 partout — rarement « une attaque », le plus souvent un simple secret désynchronisé.

Prêt à passer en production

Dès que votre endpoint signe, analyse et répond correctement en moins de 10 secondes en local, il vous suffit de remplacer l'URL dans /admin/webhook par votre adresse de production. Toute l'infrastructure TextMeFlow tourne dans l'UE (Paris), si bien que votre trafic de test et de production reste lui aussi dans l'UE. Pas encore de compte ? Le forfait gratuit vous offre 50 messages par mois, pour toujours — de quoi tester tout ce flux de bout en bout. Démarrez gratuitement.

Envie d'envoyer des messages WhatsApp via API ?

Gratuit pour toujours jusqu'à 50 messages/mois. Scannez un QR et envoyez votre premier message en 5 minutes.

Gratuit pour toujours