WebhookRelay

Debug webhook integrations without the headache. Get a permanent URL, inspect every request, and forward to your local machine with our CLI tunnel.

What is WebhookRelay?

WebhookRelay is a hosted webhook relay and inspection service for developers and integration engineers. It solves the daily pain of building and debugging webhook integrations without a public endpoint available during local development.

Relay Mode

Receive webhooks at a persistent public URL and forward them to a local or remote target endpoint. Use it to route Stripe, GitHub, Twilio, or any webhook sender to localhost or a staging server.

Inspect Mode

Receive webhooks and log the full request: headers, body, IP, timestamp, status code, payload size. Debug exactly what a third-party sender is delivering.

CLI Tunnel Agent

A small CLI binary that opens an authenticated persistent connection to the relay server and receives forwarded payloads to a local port. No SSH, no ngrok dependency.

Features

• Webhook Inspection — Log full request details: headers, body, IP, timestamp
• Request Forwarding — Forward incoming webhooks to any URL with automatic retry
• CLI Tunnel Agent — Forward webhooks directly to localhost during development
• Webhook Replay — Re-send logged webhooks with a single click
• Permanent URLs — Your endpoint URL stays the same, forever
• $19/month — Simple, transparent pricing. No free tier, no abuse.

Quick Start

1. Create an account

Sign up at [your deployment URL] and subscribe for $19/month.

2. Get your relay URL

After onboarding, you'll see your unique relay URL:

https://your-domain.com/api/relay/abc123xyz

3. Send a test webhook

curl -X POST https://your-domain.com/api/relay/abc123xyz \
  -H "Content-Type: application/json" \
  -d '{"event": "test", "message": "Hello!"}'

4. View in dashboard

Open your dashboard to see the request details including headers, body, and source IP.

CLI Tunnel

Forward webhooks directly to your local development server.

Installation

npm install -g webhookrelay-cli

Usage

# Start the tunnel (requires your API token from the dashboard)
webhookrelay listen --token <your-token> --port 3000

# The CLI will show your relay URL and forward incoming webhooks to localhost:3000

Configuration

Create ~/.webhookrelay/config.json:

{
  "token": "tok_xxxxxxxxxxxx",
  "port": 3000
}

Tech Stack

• Framework: Next.js (App Router)
• Database: PostgreSQL via Prisma
• Auth: Clerk
• Payments: Stripe
• Hosting: Vercel

Project Structure

├── app/
│   ├── api/
│   │   ├── relay/[slug]/      # Webhook ingestion endpoint
│   │   ├── endpoints/         # User endpoint management
│   │   ├── logs/              # Webhook log access
│   │   └── stripe/            # Payment webhooks
│   ├── dashboard/              # Main dashboard
│   ├── onboarding/            # Post-signup flow
│   └── pricing/               # Pricing page
├── components/                 # React components
├── lib/
│   ├── prisma.ts             # Database client
│   └── forward.ts            # HTTP forwarding logic
├── ws-server/                 # WebSocket server (separate deploy)
└── cli/                      # CLI tunnel agent (separate package)

API Endpoints

Public (No Auth)

Method	Endpoint	Description
POST	/api/relay/[slug]	Receive and forward webhooks
GET	/api/relay/[slug]	Health check

Protected (Clerk Auth)

Method	Endpoint	Description
GET	/api/endpoints/mine	Get user's endpoint and slug
POST	/api/endpoints/forward	Update forward URL
GET	/api/logs	List webhook logs (paginated)
GET	/api/logs/[id]	Get single log details
POST	/api/logs/[id]/replay	Replay webhook to forward target

Environment Variables

# Database
DATABASE_URL="postgresql://..."

# Clerk Authentication
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY="pk_test_..."
CLERK_SECRET_KEY="sk_test_..."

# Stripe Payments
STRIPE_SECRET_KEY="sk_test_..."
STRIPE_WEBHOOK_SECRET="whsec_..."
NEXT_PUBLIC_STRIPE_PRICE_ID="price_..."

# WebSocket Server (CLI tunnel)
WS_SERVER_INTERNAL_URL="http://linode:3001"
WS_SERVER_INTERNAL_SECRET="secret"

# App URL
NEXT_PUBLIC_APP_URL="https://your-domain.com"

Development

Prerequisites

• Node.js 18+
• PostgreSQL database
• Stripe account (for payments)
• Clerk account (for authentication)

Setup

# Install dependencies
npm install

# Set up environment variables
cp .env.example .env.local
# Edit .env.local with your credentials

# Push database schema
npx prisma db push

# Start development server
npm run dev

WebSocket Server

The CLI tunnel requires a separate WebSocket server running on a VPS (not Vercel, since Vercel doesn't support persistent connections).

cd ws-server
npm install
npm start

Deployment

Vercel (Main App)

1. Connect your GitHub repository to Vercel
2. Add all environment variables
3. Deploy

Linode (WebSocket Server)

# SSH into your Linode VPS
ssh user@your-linode-ip

# Clone the repository
git clone https://forgejo.tail018ac4.ts.net/joe/WebhookRelay
cd WebhookRelay/ws-server

# Install dependencies
npm install

# Start the server
PORT=3001 WS_SERVER_INTERNAL_SECRET=your-secret npm start

Set up a systemd service for auto-restart:

[Unit]
Description=WebhookRelay WebSocket Server
After=network.target

[Service]
Type=simple
User=www-data
WorkingDirectory=/path/to/ws-server
ExecStart=/usr/bin/node index.js
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

Pricing

$19/month — Single paid tier, no free tier.

• 14-day money-back guarantee
• Unlimited webhook inspection
• Request forwarding with retry
• CLI tunnel agent
• Webhook replay
• All future features included

License

MIT