Documentation

WebhookLens is EU-hosted webhook observability. Receive, inspect, replay, and forward webhooks with full visibility.

1. Create a free account
   Sign up at app.webhooklens.cloud — no credit card required to start.
2. Add an endpoint
   In the dashboard, create an endpoint with the target URL where your webhooks should be forwarded. WebhookLens generates a unique proxy URL.
3. Point your provider and send a test webhook
   Configure your provider to send to the generated URL, then: curl -X POST https://proxy.webhooklens.cloud/wh/your-tenant/your-endpoint -H "Content-Type: application/json" -d '{"test": true}'

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://proxy.webhooklens.cloud/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 can cryptographically verify the webhook signature using the provider's signing algorithm. Signature verification (checking the HMAC against your signing secret) is currently supported for Stripe and GitHub. If verification fails, the event is flagged but still stored and forwarded (unless you enable strict mode).

For 9 more providers, WebhookLens auto-detects and labels the source by inspecting well-known signature headers — no secret required. This lets you filter and inspect events by provider even without full cryptographic verification.

Example: Stripe signature verification

# When creating the endpoint, set the provider and signing secret
curl -X POST https://app.webhooklens.cloud/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

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 https://app.webhooklens.cloud/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 https://app.webhooklens.cloud/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 https://app.webhooklens.cloud/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 https://app.webhooklens.cloud/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

The API base URL is https://app.webhooklens.cloud. Authenticated endpoints require a Bearer token — either a JWT obtained from login, or an API key created in Settings → API Keys (passed as Authorization: Bearer whl_<key>).

Authentication

curl -X POST https://app.webhooklens.cloud/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 https://app.webhooklens.cloud/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "password": "securepassword"}'

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

Endpoints API

curl https://app.webhooklens.cloud/api/endpoints \
  -H "Authorization: Bearer YOUR_TOKEN"

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

curl -X POST https://app.webhooklens.cloud/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 https://app.webhooklens.cloud/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 "https://app.webhooklens.cloud/api/events?limit=50&status=failed" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Filter by endpoint
curl "https://app.webhooklens.cloud/api/events?endpoint_id=EP_ID&limit=20" \
  -H "Authorization: Bearer YOUR_TOKEN"Copy

curl -X POST https://app.webhooklens.cloud/api/events/EVT_ID/replay \
  -H "Authorization: Bearer YOUR_TOKEN"

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

Analytics API

curl "https://app.webhooklens.cloud/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 https://app.webhooklens.cloud/api/billing/quota \
  -H "Authorization: Bearer YOUR_TOKEN"

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

curl -X POST https://app.webhooklens.cloud/api/billing/checkout \
  -H "Authorization: Bearer YOUR_TOKEN"

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

curl -X POST https://app.webhooklens.cloud/api/billing/portal \
  -H "Authorization: Bearer YOUR_TOKEN"

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

MCP Server

WebhookLens exposes a Model Context Protocol server so you can query your webhook data straight from AI assistants like Claude. Ask in plain language — "what failed in the last hour?", "show me the last Stripe event", "replay event EVT_123" — and the assistant calls WebhookLens for you. Every tool is scoped to your workspace, so an assistant only ever sees your own data.

Connecting

The server lives at https://app.webhooklens.cloud/mcp and authenticates with OAuth. There is no API key to copy — you sign in with your normal WebhookLens account and approve access once.

Claude Code (CLI)

claude mcp add --transport http webhooklens https://app.webhooklens.cloud/mcpCopy

On first use your browser opens to sign in to WebhookLens (password or GitHub) and approve access. After that, the assistant can call the tools below.

Claude.ai (web)

Add a custom connector with the URL https://app.webhooklens.cloud/mcp and complete the same sign-in. The web connector is OAuth-only.

Available Tools

replay_event is the only tool that writes anything; the other six are read-only.