Documentation

WebhookLens is an open-source webhook infrastructure platform. Receive, inspect, replay, and forward webhooks with full visibility. Self-host for free or use the managed cloud.

1. Start the stack
   docker compose up -d — launches PostgreSQL, ClickHouse, Redis, and WebhookLens.
2. Open the dashboard
   Navigate to http://localhost:3000. Sign up to create your tenant.
3. Create an endpoint and send a test webhook
   Create an endpoint in the dashboard, then: curl -X POST http://localhost:8080/wh/your-tenant/your-endpoint -H "Content-Type: application/json" -d '{"test": true}'

Requirements

Docker (recommended)

• Docker 20+ and Docker Compose v2+
• 1 CPU, 1 GB RAM minimum (2 CPU, 4 GB recommended)

Single binary

• Go 1.25+ (for building from source)
• PostgreSQL 16+
• ClickHouse 24+
• Redis 7+
• 1 CPU, 1 GB RAM minimum (2 CPU, 4 GB recommended)

Installation — Docker Compose

The recommended way to run WebhookLens. A single file brings up the entire stack: PostgreSQL, ClickHouse, Redis, and the WebhookLens server.

Download and start

# Download the community compose file
curl -fsSL https://raw.githubusercontent.com/webhooklens/webhooklens/main/deploy/docker-compose.community.yml \
  -o docker-compose.yml

# Start the stack
docker compose up -dCopy

The dashboard is available at http://localhost:3000 and the webhook proxy at http://localhost:8080.

Full docker-compose.community.yml

# 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:Copy

Installation — Single Binary

Download a pre-built binary or compile from source. Requires PostgreSQL, ClickHouse, and Redis running separately.

Pre-built binary

# Download the latest release
curl -fsSL https://github.com/webhooklens/webhooklens/releases/latest/download/webhooklens-linux-amd64 \
  -o webhooklens
chmod +x webhooklens

# Run with a config file
./webhooklens --config config.yamlCopy

Build from source

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

./webhooklens --config config.yamlCopy

Configuration

WebhookLens can be configured via a YAML config file or environment variables. Environment variables use the WHL_ prefix with double underscores for nesting.

Server

Database

Authentication

Rate Limiting

Stripe Billing

Required only for cloud/SaaS mode with paid plans.

Email

Configure email delivery for password resets and notifications. Uses Resend.

Example 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: "your-random-secret-at-least-32-characters"

retention:
  events_days: 30

rate_limit:
  api_per_tenant: 100
  auth_per_ip: 10Copy

Webhook Proxy

WebhookLens acts as a reverse proxy for your webhooks. Point your providers to the proxy URL and WebhookLens receives, logs, validates, and forwards every request to your actual endpoint.

Receiving Webhooks

The proxy URL follows this pattern:

POST https://your-domain:8080/wh/{tenant-slug}/{endpoint-slug}Copy

When a webhook arrives, WebhookLens:

1. Receives the full HTTP request (method, headers, body, query params)
2. Stores the event in ClickHouse for analytics and PostgreSQL for inspection
3. Validates the signature (if a provider is configured on the endpoint)
4. Applies transforms (if any are configured)
5. Forwards the request to the configured target URL
6. Records the response status, latency, and any errors

Retry policy

Failed deliveries (5xx responses or timeouts) are retried with exponential backoff:

After 5 failed retries the event is marked as failed. You can manually replay it from the dashboard or API at any time.

Signature Validation

When you configure a provider on an endpoint, WebhookLens automatically validates the webhook signature using the provider's signing algorithm. If validation fails, the event is flagged but still stored and forwarded (unless you enable strict mode).

Example: Stripe signature verification

# When creating the endpoint, set the provider and signing secret
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_..."
  }'Copy

Supported Providers

WebhookLens supports automatic signature validation for the following providers:

Dashboard

Events & Inspector

The events page shows all incoming webhooks in real-time with auto-refresh. Each row shows:

• Status — forwarded (green), failed (red), replayed (blue), timeout (yellow)
• Provider — auto-detected from headers (Stripe, GitHub, Shopify, etc.)
• Endpoint — which endpoint received the webhook
• Latency — round-trip time to forward and receive a response
• Timestamp — relative time ("2s ago") with full ISO timestamp on hover

Click any event to open the inspector:

• Request tab: headers, body (syntax-highlighted JSON/XML), query parameters
• Response tab: target response status, headers, body
• Timeline tab: full delivery timeline including retries
• Replay button: re-send the exact same request to the target

Endpoints

Endpoints are the core abstraction. Each endpoint has:

• A unique slug that forms part of the proxy URL
• A target URL where webhooks are forwarded
• An optional provider for signature validation
• Optional transforms for payload manipulation
• Optional routing rules for multi-destination fan-out

Analytics

The analytics dashboard provides real-time metrics powered by ClickHouse:

• Volume — total events over time (1h, 24h, 7d, 30d)
• Success rate — percentage of 2xx responses
• Latency — P50, P95, P99 percentiles
• Per-provider breakdown — volume and success by provider
• Per-endpoint breakdown — volume and success by endpoint

Alerts

Configure alerts to be notified when something goes wrong:

• Failure threshold — alert when error rate exceeds N% over a time window
• Latency threshold — alert when P95 latency exceeds N ms
• No events — alert when no events received for N minutes

Notifications can be sent to Slack (via incoming webhook) or to a custom webhook URL.

# Create an alert
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/..."
  }'Copy

Transforms & Routing

Payload Transforms

Transforms let you modify webhook payloads before they are forwarded to the target. This is useful for enriching data, removing sensitive fields, or adapting payloads to your API format.

Transform types

Example: add a field and a header

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"}
    ]
  }'Copy

Dry-run test

Test your transforms without actually forwarding:

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}
  }'

# Response:
# {"event": "payment.completed", "amount": 4999, "enriched": true}Copy

Smart Routing

Route a single webhook to multiple destinations based on conditions. This enables fan-out, conditional processing, and fallback targets.

Routing conditions

Example: fan-out to 3 targets

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"}
    ]
  }'Copy

API Reference

All API endpoints are served on the API port (default :3000). Authenticated endpoints require a Bearer token obtained from login.

Authentication

curl -X POST http://localhost:3000/api/auth/signup \
  -H "Content-Type: application/json" \
  -d '{
    "email": "you@example.com",
    "password": "securepassword",
    "tenant_name": "my-project"
  }'

# Response: {"token": "eyJhbG...", "tenant": {"id": "...", "slug": "my-project"}}Copy

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

# Response: {"token": "eyJhbG..."}Copy

Endpoints API

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

# Response: [{"id": "...", "slug": "stripe-prod", "target_url": "https://...", ...}]Copy

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_..."
  }'Copy

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

Events API

# List recent events
curl "http://localhost:3000/api/events?limit=50&status=failed" \
  -H "Authorization: Bearer YOUR_TOKEN"

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

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

# Response: {"status": "replayed", "response_code": 200, "latency_ms": 142}Copy

Analytics API

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

# Response:
# {
#   "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}
# }Copy

Billing API

Available in cloud mode only.

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

# Response: {"plan": "starter", "events_used": 12847, "events_limit": 50000, ...}Copy

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

# Response: {"checkout_url": "https://checkout.stripe.com/..."}Copy

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

# Response: {"portal_url": "https://billing.stripe.com/..."}Copy

CLI Reference

Installation

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

Commands

Login

# Authenticate with a WebhookLens server
webhooklens-cli login --server https://app.webhooklens.cloud

# For self-hosted
webhooklens-cli login --server http://localhost:3000Copy

Listen (local tunnel)

# Forward webhooks to a local development server
webhooklens-cli listen --port 4000

# Specify an endpoint
webhooklens-cli listen --port 4000 --endpoint stripe-prodCopy

Events

# List recent events
webhooklens-cli events list

# Show event details
webhooklens-cli events show EVT_ID

# Replay an event to a different URL
webhooklens-cli events replay EVT_ID --to http://localhost:4000/webhookCopy

Self-Hosting Guide

Production Deployment

For production, we recommend running behind Caddy for automatic HTTPS and using the production Docker Compose file.

TLS with Caddy

Caddy automatically provisions and renews Let's Encrypt TLS certificates.

Caddyfile

# /etc/caddy/Caddyfile

webhooks.example.com {
    reverse_proxy localhost:3000
}

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

# Start Caddy
sudo caddy run --config /etc/caddy/CaddyfileCopy

Backup & Restore

Back up PostgreSQL (primary data) regularly. ClickHouse data can be regenerated from events if needed.

Backup script

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

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

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

# Keep last 30 backups
ls -t "${BACKUP_DIR}"/pg_*.sql.gz | tail -n +31 | xargs rm -f

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

Cron schedule

# Run daily at 2 AM
0 2 * * * /opt/webhooklens/backup-webhooklens.sh >> /var/log/webhooklens-backup.log 2>&1Copy

Restore

# Restore from backup
gunzip -c "/backups/webhooklens/pg_20260411_020000.sql.gz" | \
  docker exec -i webhooklens-postgres-1 \
    psql -U webhooklens webhooklensCopy

Monitoring

WebhookLens exposes a health endpoint for uptime checks and monitoring:

curl http://localhost:3000/healthz

# Response (healthy):
# {"status": "ok", "postgres": "ok", "clickhouse": "ok", "redis": "ok"}

# Response (degraded):
# {"status": "degraded", "postgres": "ok", "clickhouse": "error", "redis": "ok"}Copy

Use this endpoint with your monitoring system (UptimeRobot, Datadog, Prometheus blackbox exporter, etc.) to get alerted when any component is unhealthy.