Construire un webhook receiver avec Node.js et Express en 2026

Vous allez construire un serveur webhook fonctionnel en 15 minutes avec Express 5.2.1 et Node.js 18+, capable de recevoir, vérifier et logger des payloads JSON depuis Stripe, GitHub ou tout autre service. Documentation officielle Express.

Ce que vous allez construire et pourquoi en 2026

Un serveur Express qui écoute les webhooks entrants, vérifie la signature HMAC-SHA256 de chaque requête, parse le payload JSON et le stocke dans un fichier log structuré. Prérequis: Node.js 18+ installé (node -v pour vérifier), 8 Go RAM minimum, macOS/Linux/Windows. Temps estimé: 15 minutes. Licence Express: MIT — gratuit et open-source.

Installation: commandes exactes à copier

mkdir webhook-receiver && cd webhook-receiver
npm init -y
npm install express@5.2.1
npm install --save-dev nodemon

Résultat attendu: added 2 packages dans node_modules/. Erreur courante: npm ERR! code EACCES → lancer sudo chown -R $(whoami) ~/.npm puis réessayer.

Configuration: les fichiers et variables à définir

Créer le fichier .env à la racine:

PORT=3000
WEBHOOK_SECRET=whsec_votre_cle_secrete_ici
LOG_DIR=./logs

Installer dotenv pour charger ces variables:

npm install dotenv

Chaque variable: PORT = port d'écoute du serveur (3000 par défaut), WEBHOOK_SECRET = clé secrète fournie par le service émetteur (Stripe, GitHub, etc.), LOG_DIR = répertoire où stocker les payloads reçus.

Le code du projet: construire la fonctionnalité principale

Créer server.js:

require('dotenv').config();
const crypto = require('crypto');
const fs = require('fs');
const path = require('path');
const express = require('express'); const app = express();
const PORT = process.env.PORT || 3000;
const WEBHOOK_SECRET = process.env.WEBHOOK_SECRET;
const LOG_DIR = process.env.LOG_DIR || './logs'; // Créer le répertoire de logs s'il n'existe pas
if (!fs.existsSync(LOG_DIR)) { fs.mkdirSync(LOG_DIR, { recursive: true });
} // Middleware pour lire le body en raw buffer (nécessaire pour vérifier la signature)
app.use('/webhook', express.raw({ type: 'application/json' })); // Route webhook principale
app.post('/webhook', (req, res) => { const sig = req.headers['x-signature-256'] || req.headers['x-hub-signature-256'] || ''; const payload = req.body; // Vérification HMAC-SHA256 const expectedSig = crypto.createHmac('sha256', WEBHOOK_SECRET).update(payload).digest('hex'); if (sig!== 'sha256=' + expectedSig) { return res.status(401).json({ error: 'Signature invalide' }); } // Parser le payload JSON let event; try { event = JSON.parse(payload.toString()); } catch (e) { return res.status(400).json({ error: 'Payload JSON invalide' }); } // Logger l'événement dans un fichier horodaté const timestamp = new Date().toISOString().replace(/[:.]/g, '-'); const logFile = path.join(LOG_DIR, 'webhook-' + timestamp + '.json'); fs.writeFileSync(logFile, JSON.stringify(event, null, 2)); console.log('✓ Webhook reçu: ' + (event.type || 'type inconnu') + ' — sauvé dans ' + logFile); res.status(200).json({ received: true });
}); // Route santé
app.get('/health', (req, res) => { res.json({ status: 'ok', uptime: process.uptime() });
}); app.listen(PORT, () => { console.log('Webhook receiver démarré sur le port ' + PORT);
});

Le code vérifie la signature HMAC-SHA256 de chaque requête entrante — sans cette vérification, n'importe qui peut envoyer des faux webhooks à votre endpoint. La comparaison sig!== 'sha256=' + expectedSig rejette les requêtes non signées. Le payload est loggé dans ./logs/ avec un nom de fichier horodaté.

Tester et valider que ça fonctionne

Lancer le serveur:

npx nodemon server.js

Envoyer un webhook de test avec curl:

SECRET="whsec_votre_cle_secrete_ici"
PAYLOAD='{"type":"test.event","data":{"message":"hello"}}'
SIG=$(echo -n "$PAYLOAD" | openssl dgst -sha256 -hmac "$SECRET" | awk '{print $NF}')
curl -X POST http://localhost:3000/webhook \ -H "Content-Type: application/json" \ -H "x-signature-256: sha256=$SIG" \ -d "$PAYLOAD"

Résultat attendu dans le terminal: ✓ Webhook reçu: test.event — sauvé dans./logs/webhook-2026-05-13T.. Si vous recevez 401 Signature invalide, vérifiez que WEBHOOK_SECRET dans .env correspond exactement au secret utilisé pour générer la signature.

Vérifier la route santé: curl http://localhost:3000/health → {"status":"ok","uptime":.}

Déployer et utiliser en production

Sur un VPS (Ubuntu 22.04+), utiliser systemd pour garder le serveur actif:

sudo nano /etc/systemd/system/webhook-receiver.service

[Unit]
Description=Webhook Receiver Node.js
After=network.target [Service]
Type=simple
User=webhook
WorkingDirectory=/opt/webhook-receiver
ExecStart=/usr/bin/node server.js
Restart=on-failure
RestartSec=5
Environment=NODE_ENV=production [Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable webhook-receiver
sudo systemctl start webhook-receiver
sudo systemctl status webhook-receiver

Pour exposer le webhook derrière HTTPS, configurer Nginx en reverse proxy:

server { listen 443 ssl; server_name webhook.votre-domaine.fr; ssl_certificate /etc/letsencrypt/live/webhook.votre-domaine.fr/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/webhook.votre-domaine.fr/privkey.pem; location / { proxy_pass http://127.0.0.1:3000; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; }
}

Pour mettre à jour Express: npm update express puis sudo systemctl restart webhook-receiver.

Aller plus loin: 3 extensions concrètes

1. Ajouter un endpoint Stripe: utiliser stripe.webhooks.constructEvent() du package stripe (npm install stripe) pour vérifier automatiquement les signatures Stripe et traiter les événements invoice.paid, customer.created, etc.

2. Relayer vers Discord ou Slack: installer axios (npm install axios) et ajouter un axios.post() vers le webhook Discord/Slack dans la route /webhook pour recevoir une notification en temps réel à chaque événement.

3. Stocker en base PostgreSQL: installer pg (npm install pg) et remplacer le fs.writeFileSync par un INSERT INTO webhook_events(type, payload, received_at) pour interroger et filtrer les événements avec SQL.