Documentation

WebhookLens est une plateforme d'infrastructure webhook open source. Recevez, inspectez, rejouez et transmettez des webhooks avec une visibilité totale. Auto-hébergez gratuitement ou utilisez le cloud géré.

1. Démarrez la stack
   docker compose up -d — lance PostgreSQL, ClickHouse, Redis et WebhookLens.
2. Ouvrez le tableau de bord
   Accédez à http://localhost:3000. Inscrivez-vous pour créer votre tenant.
3. Créez un endpoint et envoyez un webhook de test
   Créez un endpoint dans le tableau de bord, puis : curl -X POST http://localhost:8080/wh/your-tenant/your-endpoint -H "Content-Type: application/json" -d '{"test": true}'

Prérequis

Docker (recommandé)

• Docker 20+ et Docker Compose v2+
• 1 CPU, 1 Go de RAM minimum (2 CPU, 4 Go recommandés)

Binaire unique

• Go 1.25+ (pour compiler depuis les sources)
• PostgreSQL 16+
• ClickHouse 24+
• Redis 7+
• 1 CPU, 1 Go de RAM minimum (2 CPU, 4 Go recommandés)

Installation — Docker Compose

La méthode recommandée pour exécuter WebhookLens. Un seul fichier lance toute la stack : PostgreSQL, ClickHouse, Redis et le serveur WebhookLens.

Télécharger et démarrer

# Télécharger le fichier compose communauté
curl -fsSL https://raw.githubusercontent.com/webhooklens/webhooklens/main/deploy/docker-compose.community.yml \
  -o docker-compose.yml

# Démarrer la stack
docker compose up -dCopier

Le tableau de bord est disponible sur http://localhost:3000 et le proxy webhook sur http://localhost:8080.

Fichier docker-compose.community.yml complet

# WebhookLens Community Edition — Docker Compose
# Usage: docker compose -f docker-compose.community.yml up -d
# Dashboard: http://localhost:3000
# Proxy:     http://localhost:8080

version: '3.8'

services:
  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: webhooklens
      POSTGRES_PASSWORD: webhooklens
      POSTGRES_DB: webhooklens
    volumes:
      - pg_data:/var/lib/postgresql/data
      - ./migrations/postgres:/docker-entrypoint-initdb.d
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U webhooklens"]
      interval: 5s
      retries: 5

  clickhouse:
    image: clickhouse/clickhouse-server:24-alpine
    volumes:
      - ch_data:/var/lib/clickhouse
      - ./migrations/clickhouse:/docker-entrypoint-initdb.d
    healthcheck:
      test: ["CMD", "clickhouse-client", "--query", "SELECT 1"]
      interval: 5s
      retries: 5

  redis:
    image: redis:7-alpine
    volumes:
      - redis_data:/data
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
      retries: 5

  webhooklens:
    image: webhooklens/webhooklens:latest
    ports:
      - "3000:3000"
      - "8080:8080"
    environment:
      WHL_DATABASE__POSTGRES_URL: postgres://webhooklens:webhooklens@postgres:5432/webhooklens?sslmode=disable
      WHL_DATABASE__CLICKHOUSE_URL: clickhouse://clickhouse:9000/webhooklens
      WHL_DATABASE__REDIS_URL: redis://redis:6379
      WHL_AUTH__JWT_SECRET: change-me-in-production-use-64-chars-minimum
    depends_on:
      postgres: { condition: service_healthy }
      clickhouse: { condition: service_healthy }
      redis: { condition: service_healthy }
    restart: unless-stopped

volumes:
  pg_data:
  ch_data:
  redis_data:Copier

Installation — Binaire unique

Téléchargez un binaire précompilé ou compilez depuis les sources. Nécessite PostgreSQL, ClickHouse et Redis exécutés séparément.

Binaire précompilé

# Télécharger la dernière version
curl -fsSL https://github.com/webhooklens/webhooklens/releases/latest/download/webhooklens-linux-amd64 \
  -o webhooklens
chmod +x webhooklens

# Lancer avec un fichier de configuration
./webhooklens --config config.yamlCopier

Compiler depuis les sources

git clone https://github.com/webhooklens/webhooklens.git
cd webhooklens
go build -o webhooklens ./cmd/server

./webhooklens --config config.yamlCopier

Configuration

WebhookLens peut être configuré via un fichier YAML ou des variables d'environnement. Les variables d'environnement utilisent le préfixe WHL_ avec des doubles underscores pour l'imbrication.

Serveur

Base de données

Authentification

Limitation de débit

Facturation Stripe

Requis uniquement en mode cloud/SaaS avec des forfaits payants.

Email

Configurez la distribution d'e-mails pour les réinitialisations de mot de passe et les notifications. Utilise Resend.

Exemple config.yaml

server:
  proxy_port: 8080
  api_port: 3000
  debug: false

database:
  postgres_url: "postgres://user:pass@localhost:5432/webhooklens?sslmode=disable"
  clickhouse_url: "clickhouse://localhost:9000/webhooklens"
  redis_url: "redis://localhost:6379"

auth:
  jwt_secret: "votre-secret-aleatoire-32-caracteres-minimum"

retention:
  events_days: 30

rate_limit:
  api_per_tenant: 100
  auth_per_ip: 10Copier

Proxy Webhook

WebhookLens agit comme un proxy inverse pour vos webhooks. Pointez vos fournisseurs vers l'URL du proxy et WebhookLens reçoit, journalise, valide et transmet chaque requête vers votre endpoint réel.

Réception des webhooks

L'URL du proxy suit ce schéma :

POST https://votre-domaine:8080/wh/{tenant-slug}/{endpoint-slug}Copier

Lorsqu'un webhook arrive, WebhookLens :

1. Reçoit la requête HTTP complète (méthode, en-têtes, corps, paramètres de requête)
2. Stocke l'événement dans ClickHouse pour l'analytique et PostgreSQL pour l'inspection
3. Valide la signature (si un fournisseur est configuré sur l'endpoint)
4. Applique les transforms (si configurés)
5. Transmet la requête à l'URL cible configurée
6. Enregistre le code de réponse, la latence et les éventuelles erreurs

Politique de relance

Les livraisons échouées (réponses 5xx ou timeouts) sont relancées avec un backoff exponentiel :

Après 5 échecs consécutifs, l'événement est marqué comme failed. Vous pouvez le rejouer manuellement depuis le tableau de bord ou l'API à tout moment.

Validation de signature

Lorsque vous configurez un fournisseur sur un endpoint, WebhookLens valide automatiquement la signature du webhook en utilisant l'algorithme de signature du fournisseur. En cas d'échec de validation, l'événement est signalé mais reste stocké et transmis (sauf si vous activez le mode strict).

Exemple : vérification de signature Stripe

# Lors de la création de l'endpoint, définissez le fournisseur et le secret de signature
curl -X POST http://localhost:3000/api/endpoints \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "stripe-payments",
    "target_url": "https://api.example.com/webhooks/stripe",
    "provider": "stripe",
    "signing_secret": "whsec_..."
  }'Copier

Fournisseurs supportés

WebhookLens prend en charge la validation automatique de signature pour les fournisseurs suivants :

Tableau de bord

Événements & Inspecteur

La page des événements affiche tous les webhooks entrants en temps réel avec actualisation automatique. Chaque ligne indique :

• Statut — transmis (vert), échoué (rouge), rejoué (bleu), timeout (jaune)
• Fournisseur — détecté automatiquement depuis les en-têtes (Stripe, GitHub, Shopify, etc.)
• Endpoint — quel endpoint a reçu le webhook
• Latence — temps aller-retour pour transmettre et recevoir une réponse
• Horodatage — temps relatif ("il y a 2s") avec l'horodatage ISO complet au survol

Cliquez sur un événement pour ouvrir l'inspecteur :

• Onglet Requête : en-têtes, corps (JSON/XML avec coloration syntaxique), paramètres de requête
• Onglet Réponse : code de réponse cible, en-têtes, corps
• Onglet Chronologie : chronologie complète de livraison incluant les relances
• Bouton Replay : renvoie exactement la même requête à la cible

Endpoints

Les endpoints sont l'abstraction centrale. Chaque endpoint possède :

• Un slug unique qui fait partie de l'URL du proxy
• Une URL cible vers laquelle les webhooks sont transmis
• Un fournisseur optionnel pour la validation de signature
• Des transforms optionnels pour la manipulation du payload
• Des règles de routage optionnelles pour la distribution multi-destination

Analytique

Le tableau de bord analytique fournit des métriques en temps réel propulsées par ClickHouse :

• Volume — total des événements dans le temps (1h, 24h, 7j, 30j)
• Taux de succès — pourcentage de réponses 2xx
• Latence — percentiles P50, P95, P99
• Répartition par fournisseur — volume et succès par fournisseur
• Répartition par endpoint — volume et succès par endpoint

Alertes

Configurez des alertes pour être notifié en cas de problème :

• Seuil d'échec — alerte quand le taux d'erreur dépasse N% sur une fenêtre temporelle
• Seuil de latence — alerte quand la latence P95 dépasse N ms
• Absence d'événements — alerte quand aucun événement n'est reçu pendant N minutes

Les notifications peuvent être envoyées à Slack (via webhook entrant) ou à une URL webhook personnalisée.

# Créer une alerte
curl -X POST http://localhost:3000/api/alerts \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "High failure rate",
    "type": "failure_rate",
    "threshold": 10,
    "window_minutes": 5,
    "channel": "slack",
    "slack_webhook_url": "https://hooks.slack.com/services/..."
  }'Copier

Transforms & Routage

Transforms de payload

Les transforms vous permettent de modifier les payloads des webhooks avant leur transmission vers la cible. Utile pour enrichir des données, supprimer des champs sensibles ou adapter les payloads à votre format d'API.

Types de transforms

Exemple : ajouter un champ et un en-tête

curl -X PATCH http://localhost:3000/api/endpoints/EP_ID \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "transforms": [
      {"type": "set_field", "path": "meta.source", "value": "stripe"},
      {"type": "add_header", "key": "X-Source", "value": "webhooklens"},
      {"type": "remove_field", "path": "data.object.metadata.internal"}
    ]
  }'Copier

Test à blanc (dry-run)

Testez vos transforms sans effectuer la transmission :

curl -X POST http://localhost:3000/api/transforms/test \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "transforms": [
      {"type": "set_field", "path": "enriched", "value": true}
    ],
    "payload": {"event": "payment.completed", "amount": 4999}
  }'

# Réponse :
# {"event": "payment.completed", "amount": 4999, "enriched": true}Copier

Routage intelligent

Routez un seul webhook vers plusieurs destinations selon des conditions. Permet la distribution en éventail, le traitement conditionnel et les cibles de secours.

Conditions de routage

Exemple : distribution vers 3 cibles

curl -X PATCH http://localhost:3000/api/endpoints/EP_ID \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "target_url": "https://primary.example.com/webhook",
    "routes": [
      {"url": "https://analytics.example.com/ingest", "condition": "all"},
      {"url": "https://backup.example.com/webhook", "condition": "all"},
      {"url": "https://alerts.example.com/failure", "condition": "on_failure"}
    ]
  }'Copier

Référence API

Tous les endpoints API sont servis sur le port API (par défaut :3000). Les endpoints authentifiés nécessitent un token Bearer obtenu lors de la connexion.

Authentification

curl -X POST http://localhost:3000/api/auth/signup \
  -H "Content-Type: application/json" \
  -d '{
    "email": "vous@exemple.com",
    "password": "motdepassesecurise",
    "tenant_name": "mon-projet"
  }'

# Réponse : {"token": "eyJhbG...", "tenant": {"id": "...", "slug": "mon-projet"}}Copier

curl -X POST http://localhost:3000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "vous@exemple.com", "password": "motdepassesecurise"}'

# Réponse : {"token": "eyJhbG..."}Copier

API Endpoints

curl http://localhost:3000/api/endpoints \
  -H "Authorization: Bearer YOUR_TOKEN"

# Réponse : [{"id": "...", "slug": "stripe-prod", "target_url": "https://...", ...}]Copier

curl -X POST http://localhost:3000/api/endpoints \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "stripe-prod",
    "target_url": "https://api.example.com/webhooks/stripe",
    "provider": "stripe",
    "signing_secret": "whsec_..."
  }'Copier

curl -X PATCH http://localhost:3000/api/endpoints/EP_ID \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"target_url": "https://nouvelle-cible.example.com/hook"}'Copier

API Événements

# Lister les événements récents
curl "http://localhost:3000/api/events?limit=50&status=failed" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Filtrer par endpoint
curl "http://localhost:3000/api/events?endpoint_id=EP_ID&limit=20" \
  -H "Authorization: Bearer YOUR_TOKEN"Copier

curl -X POST http://localhost:3000/api/events/EVT_ID/replay \
  -H "Authorization: Bearer YOUR_TOKEN"

# Réponse : {"status": "replayed", "response_code": 200, "latency_ms": 142}Copier

API Analytique

curl "http://localhost:3000/api/analytics/overview?period=24h" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Réponse :
# {
#   "total_events": 12847,
#   "success_rate": 99.2,
#   "p50_ms": 45,
#   "p95_ms": 210,
#   "p99_ms": 890,
#   "by_provider": [{"provider": "stripe", "count": 8420}, ...],
#   "by_status": {"forwarded": 12744, "failed": 62, "replayed": 41}
# }Copier

API Facturation

Disponible en mode cloud uniquement.

curl http://localhost:3000/api/billing/quota \
  -H "Authorization: Bearer YOUR_TOKEN"

# Réponse : {"plan": "starter", "events_used": 12847, "events_limit": 50000, ...}Copier

curl -X POST http://localhost:3000/api/billing/checkout \
  -H "Authorization: Bearer YOUR_TOKEN"

# Réponse : {"checkout_url": "https://checkout.stripe.com/..."}Copier

curl -X POST http://localhost:3000/api/billing/portal \
  -H "Authorization: Bearer YOUR_TOKEN"

# Réponse : {"portal_url": "https://billing.stripe.com/..."}Copier

Référence CLI

Installation

go install github.com/webhooklens/webhooklens/cmd/webhooklens-cli@latestCopier

Commandes

Connexion

# S'authentifier auprès d'un serveur WebhookLens
webhooklens-cli login --server https://app.webhooklens.cloud

# Pour un serveur auto-hébergé
webhooklens-cli login --server http://localhost:3000Copier

Écoute (tunnel local)

# Transmettre les webhooks vers un serveur de développement local
webhooklens-cli listen --port 4000

# Spécifier un endpoint
webhooklens-cli listen --port 4000 --endpoint stripe-prodCopier

Événements

# Lister les événements récents
webhooklens-cli events list

# Afficher les détails d'un événement
webhooklens-cli events show EVT_ID

# Rejouer un événement vers une URL différente
webhooklens-cli events replay EVT_ID --to http://localhost:4000/webhookCopier

Guide d'auto-hébergement

Déploiement en production

Pour la production, nous recommandons d'utiliser Caddy pour le HTTPS automatique et le fichier Docker Compose de production.

TLS avec Caddy

Caddy provisionne et renouvelle automatiquement les certificats TLS via Let's Encrypt.

Caddyfile

# /etc/caddy/Caddyfile

webhooks.example.com {
    reverse_proxy localhost:3000
}

proxy.example.com {
    reverse_proxy localhost:8080
}Copier

# Démarrer Caddy
sudo caddy run --config /etc/caddy/CaddyfileCopier

Sauvegarde & Restauration

Sauvegardez régulièrement PostgreSQL (données primaires). Les données ClickHouse peuvent être régénérées depuis les événements si nécessaire.

Script de sauvegarde

#!/bin/bash
# backup-webhooklens.sh

BACKUP_DIR="/backups/webhooklens"
TIMESTAMP=$(date +%Y%m%d_%H%M%S)

# Sauvegarde PostgreSQL
docker exec webhooklens-postgres-1 \
  pg_dump -U webhooklens webhooklens | \
  gzip > "${BACKUP_DIR}/pg_${TIMESTAMP}.sql.gz"

# Conserver les 30 dernières sauvegardes
ls -t "${BACKUP_DIR}"/pg_*.sql.gz | tail -n +31 | xargs rm -f

echo "Backup completed: pg_${TIMESTAMP}.sql.gz"Copier

Planification cron

# Exécuter chaque jour à 2h du matin
0 2 * * * /opt/webhooklens/backup-webhooklens.sh >> /var/log/webhooklens-backup.log 2>&1Copier

Restauration

# Restaurer depuis une sauvegarde
gunzip -c "/backups/webhooklens/pg_20260411_020000.sql.gz" | \
  docker exec -i webhooklens-postgres-1 \
    psql -U webhooklens webhooklensCopier

Supervision

WebhookLens expose un endpoint de santé pour les vérifications de disponibilité et la supervision :

curl http://localhost:3000/healthz

# Réponse (sain) :
# {"status": "ok", "postgres": "ok", "clickhouse": "ok", "redis": "ok"}

# Réponse (dégradé) :
# {"status": "degraded", "postgres": "ok", "clickhouse": "error", "redis": "ok"}Copier

Utilisez cet endpoint avec votre système de supervision (UptimeRobot, Datadog, Prometheus blackbox exporter, etc.) pour être alerté lorsqu'un composant est défaillant.