ngrok ou cloudflared : lequel choisir ?

cloudflared est gratuit et sans compte pour les tunnels éphémères. ngrok offre une URL stable et une interface d'inspection riche sur http://127.0.0.1:4040 — pratique pour rejouer les webhooks. Choisissez selon votre besoin.

Pourquoi ma signature webhook échoue-t-elle en test ?

Dans 99% des cas : votre framework parse le body avant que constructEvent() le lise. Vérifiez que vous récupérez les bytes bruts (req.text() / request.get_data() / $request->getContent() / express.raw()) en premier.

Puis-je tester sans tunnel public ?

Oui, pour des tests unitaires uniquement : générez vous-même une signature HMAC-SHA256 valide à partir de MCC_WEBHOOK_SECRET et postez-la à votre endpoint local avec curl. Mais pour valider le flux complet bout-en-bout, un tunnel reste nécessaire.

Faut-il un compte payant ngrok ?

Non, le plan gratuit ngrok suffit pour le développement. L'URL change à chaque redémarrage — il faudra alors la mettre à jour dans le dashboard MCC. cloudflared évite cette friction.

Test localTous frameworks · ngrok · cloudflared

Tester les webhooks en local

Les webhooks nécessitent une URL publique accessible depuis internet. Ce guide vous montre comment exposer votre serveur local en 2 minutes avec ngrok ou cloudflared, et comment inspecter et déboguer chaque requête.

Tester les webhooks en Sandbox

SandboxAucun argent réel, aucune transaction réelle

En mode Sandbox, MCC signe les webhooks avec votre secret webhook de test (et non le secret webhook live). Le payload contient livemode: false (champ absent en live — voir Guide Sandbox §4 pour les détails).

Format du payload Sandbox :

json

{
  "event": "payment.completed" | "payment.failed" | "payment.cancelled",
  "reference": "<votre referenceId>",
  "amount": 100,
  "status": "completed" | "failed" | "cancelled",
  "completedAt": "ISO8601 ou null",
  "livemode": false
}

Vérification HMAC (identique en sandbox et live, seul le secret change) :

Lire le body brut en bytes (req.text(), jamais req.json()).
Calculer expected = "sha256=" + hmacSha256(MCC_WEBHOOK_SECRET, rawBody).
Comparer à l'en-tête X-MCC-Signature. Si différent → 401.
Seulement APRÈS validation : JSON.parse(rawBody) et dispatch sur event.

Pour tester : déclenchez un paiement Sandbox via pay-create, ouvrez l'URL retournée, cliquez « Pay success » / « Pay fail » / « Cancel » sur le simulateur. Votre endpoint reçoit le webhook signé en moins de 2 secondes.

Pour le guide complet : Sandbox Guide.

Pourquoi un tunnel ?

Quand MonCashConnect envoie un webhook, il effectue une requête HTTP vers votre URL configurée. Si votre serveur tourne sur localhost:3000, MonCashConnect ne peut pas l'atteindre depuis internet.

Votre serveur local

localhost:3000

Tunnel (ngrok / cloudflared)

HTTPS ↔ localhost

MonCashConnect

https://xyz.ngrok-free.app

Option 1 — ngrok (recommandé)

ngrok est le tunnel le plus populaire. Le plan gratuit suffit pour le développement.

1. Installer ngrok

bash

# macOS
brew install ngrok

# Windows (Chocolatey)
choco install ngrok

# Linux / autre — télécharger sur https://ngrok.com/download
# puis déplacer l'exécutable dans votre PATH

2. Créer un compte et s'authentifier

Créez un compte gratuit sur ngrok.com, récupérez votre authtoken dans le dashboard, puis :

bash

ngrok config add-authtoken VOTRE_AUTHTOKEN

3. Démarrer le tunnel

Remplacez 3000 par le port de votre serveur local :

bash

ngrok http 3000

Vous verrez une sortie similaire :

text

Session Status     online
Account            vous@email.com (Plan: Free)
Forwarding         https://abc123.ngrok-free.app -> http://localhost:3000
                   ↑ Copiez cette URL
Web Interface      http://127.0.0.1:4040

Sur le plan gratuit, l'URL ngrok change à chaque redémarrage. Si vous relancez ngrok, pensez à mettre à jour l'URL dans votre projet MonCashConnect. Le plan payant offre des domaines statiques.

Option 2 — cloudflared (sans compte requis)

cloudflared est une alternative gratuite qui ne nécessite aucun compte. L'URL change à chaque démarrage (comme ngrok gratuit).

bash

# macOS
brew install cloudflare/cloudflare/cloudflared

# Windows (Winget)
winget install Cloudflare.cloudflared

# Linux
curl -L https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64 \
  -o /usr/local/bin/cloudflared && chmod +x /usr/local/bin/cloudflared

Lancer le tunnel :

bash

cloudflared tunnel --url http://localhost:3000

L'URL publique s'affiche dans le terminal : https://random-name.trycloudflare.com

Configurer le webhook dans MonCashConnect

Une fois votre tunnel démarré, configurez l'URL dans votre projet :

Allez dans Développeur → Projets et sélectionnez votre projet.

Dans l'onglet Webhooks, entrez votre URL tunnel : https://abc123.ngrok-free.app/webhooks/moncash(remplacez /webhooks/moncash par le chemin de votre handler).

Copiez le webhook secret affiché (whsec_…) et ajoutez-le dans votre fichier .env sous MCC_WEBHOOK_SECRET.

Redémarrez votre serveur local pour charger la nouvelle variable.

Envoyer un webhook de test avec cURL

Vous pouvez simuler un webhook MonCashConnect sans déclencher un vrai paiement. Ce script génère une signature HMAC valide et l'envoie à votre endpoint :

bash

#!/bin/bash
# Remplacez ces valeurs par les vôtres
WEBHOOK_URL="https://abc123.ngrok-free.app/webhooks/moncash"
SECRET="whsec_votre_webhook_secret"

BODY='{"event":"payment.completed","reference":"test_001","amount":500,"status":"completed","completedAt":"2026-05-06T14:21:18.000Z"}'
TS=$(date +%s)
SIG="sha256=$(echo -n "$BODY" | openssl dgst -sha256 -hmac "$SECRET" | sed 's/.*= //')"

curl -s -X POST "$WEBHOOK_URL" \
  -H "Content-Type: application/json" \
  -H "X-MCC-Signature: $SIG" \
  -H "X-MCC-Timestamp: $TS" \
  -d "$BODY"

echo " → Réponse : $?"

Pour tester un paiement échoué, changez "payment.completed" en "payment.failed" et "completed" en "failed".

Inspecter les requêtes avec le dashboard ngrok

Interface web ngrok

Pendant que ngrok tourne, ouvrez http://127.0.0.1:4040 dans votre navigateur. Vous verrez :

Toutes les requêtes entrantes avec leur corps, en-têtes et réponse
Le code de statut retourné par votre serveur
Un bouton Replay pour renvoyer la même requête sans regenerer la signature

cloudflared n'a pas d'interface d'inspection. Pour déboguer, utilisez les logs de votre serveur ou ajoutez temporairement un print(request.body) dans votre handler.

Problèmes fréquents

401 — Signature invalide

→Vérifiez que MCC_WEBHOOK_SECRET dans votre .env correspond exactement au secret affiché dans le tableau de bord (commençant par whsec_)
→Assurez-vous de redémarrer votre serveur après avoir modifié le .env
→Vérifiez que vous lisez le corps brut (Buffer/bytes) AVANT tout JSON.parse() ou json.loads()

401 — Timestamp trop ancien (> 5 minutes)

→Si votre horloge système est décalée, le timestamp généré par date +%s sera hors plage
→Vérifiez avec date +%s que l'heure est correcte
→Sur macOS avec Homebrew, assurez-vous que votre heure système est synchronisée : sudo sntp -sS time.apple.com

Connection refused / 502

→Votre serveur local n'est pas démarré, ou il écoute sur un port différent
→Vérifiez que ngrok est bien configuré sur le bon port (ngrok http 3000 si votre serveur est sur 3000)
→Si vous avez relancé ngrok, l'URL a changé — mettez à jour la configuration dans le tableau de bord

Le webhook arrive mais les logs montrent body vide

→Express : assurez-vous d'utiliser express.raw() sur la route webhook, pas express.json()
→Django : lisez request.body en premier, avant tout accès à request.POST ou request.data
→Flask : utilisez request.get_data() — pas request.json ou request.get_json() avant
→Next.js : utilisez await req.text() — pas await req.json()

ngrok URL introuvable (ERR_NGROK_3200)

→Vous avez dépassé la limite de connexions simultanées du plan gratuit (1 tunnel actif)
→Fermez d'autres sessions ngrok et relancez
→Ou utilisez cloudflared comme alternative gratuite sans limite de sessions

Guides d'intégration par framework

Next.js Express.js Laravel Django Flask Référence API