Tunnels

Tunnels let you receive webhooks on your local machine during development.

Overview

When developing webhook integrations, you need a way for external services to reach your local development server. Tunnels create a secure connection from the internet to your local machine.

External Service ──▶ WebhookRelay Tunnel ──▶ Your Local Server
     (GitHub)           (*.tunnel.webhookrelay.com)        (localhost:3000)

How It Works

1. Start the tunnel client on your local machine
2. Get a public URL (e.g., abc123.tunnel.webhookrelay.com)
3. Configure your webhook provider to use this URL
4. Webhooks are forwarded to your local server

Getting Started

1. Install the CLI

# npm
npm install -g webhookrelay-cli

# or download binary
curl -fsSL https://get.webhookrelay.com | sh

2. Login

webhookrelay login

3. Start a Tunnel

# Forward to localhost:3000
webhookrelay tunnel --port 3000

# With custom subdomain (paid plans)
webhookrelay tunnel --port 3000 --subdomain myapp

Output:

Tunnel established!
Public URL: https://abc123.tunnel.webhookrelay.com
Forwarding to: http://localhost:3000

Ready for connections...

4. Use the URL

Configure your webhook provider (GitHub, Stripe, etc.) to send webhooks to your tunnel URL.

CLI Commands

Start Tunnel

# Basic usage
webhookrelay tunnel --port 3000

# Custom local host
webhookrelay tunnel --port 3000 --host 127.0.0.1

# Custom subdomain (requires paid plan)
webhookrelay tunnel --port 3000 --subdomain myapp

# Forward to HTTPS locally
webhookrelay tunnel --port 443 --local-https

List Active Tunnels

webhookrelay tunnels list

Stop Tunnel

# Stop by subdomain
webhookrelay tunnel stop abc123

# Stop all
webhookrelay tunnel stop --all

Dashboard Management

You can also manage tunnels from the web dashboard:

1. Navigate to Tunnels in the sidebar
2. Click Create Tunnel
3. Enter a subdomain (optional)
4. Click Create
5. Copy the connection command

Tunnel Options

Option	Description
--port	Local port to forward to
--host	Local host (default: localhost)
--subdomain	Custom subdomain (paid plans)
--local-https	Use HTTPS for local connection
--inspect	Enable request inspection UI

Request Inspection

Enable inspection to see all requests passing through the tunnel:

webhookrelay tunnel --port 3000 --inspect

This opens a local web UI where you can:

• View all incoming requests
• Inspect headers and body
• Replay requests
• Filter by path or method

API Usage

Create Tunnel

curl -X POST https://api.webhookrelay.com/api/organizations/{orgId}/tunnels \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "subdomain": "myapp",
    "targetPort": 3000
  }'

List Tunnels

curl https://api.webhookrelay.com/api/organizations/{orgId}/tunnels \
  -H "Authorization: Bearer YOUR_TOKEN"

Delete Tunnel

curl -X DELETE https://api.webhookrelay.com/api/organizations/{orgId}/tunnels/{tunnelId} \
  -H "Authorization: Bearer YOUR_TOKEN"

Use Cases

Local Development

Test webhook integrations without deploying:

# Start your local server
npm run dev  # localhost:3000

# In another terminal, start the tunnel
webhookrelay tunnel --port 3000

# Configure GitHub to send webhooks to your tunnel URL

Demo Environments

Create temporary public URLs for demos:

webhookrelay tunnel --port 8080 --subdomain demo
# https://demo.tunnel.webhookrelay.com

Testing CI/CD

Test webhook-triggered pipelines locally:

webhookrelay tunnel --port 8080 --subdomain ci-test
# Point GitHub Actions webhook to tunnel

Integration with Sources

Tunnels can be used as destinations for routes:

1. Create a tunnel
2. Create a destination with the tunnel URL
3. Create a route from your source to the destination

This allows you to:

• Receive production webhooks locally
• Test transforms and filters with real data
• Debug webhook handling in your IDE

Security

Encryption

All tunnel traffic is encrypted with TLS. The tunnel URL uses HTTPS.

Authentication

Tunnels are authenticated to your account. Only you can create tunnels under your organization.

Expiration

Free tier tunnels expire after 2 hours of inactivity. Paid plans have longer or unlimited tunnel sessions.

Limitations

Plan	Tunnels	Subdomain	Session Duration
Free	1	Random	2 hours
Starter	2	Custom	8 hours
Pro	5	Custom	24 hours
Business	10	Custom	Unlimited
Enterprise	Unlimited	Custom	Unlimited

Troubleshooting

Tunnel not connecting

1. Check your internet connection
2. Verify you're logged in: webhookrelay whoami
3. Check if the port is correct and your server is running
4. Try a different port

Webhooks not arriving

1. Verify the webhook provider is using the correct URL
2. Check if your local server is running
3. Enable --inspect to see incoming requests
4. Check the tunnel logs for errors

Connection drops

1. Check your internet stability
2. The CLI will auto-reconnect on network changes
3. For long-running tunnels, use a process manager

Best Practices

1. Use custom subdomains: Easier to remember and configure

2. Don't use in production: Tunnels are for development only

3. Enable inspection: Helps debug webhook issues

4. Secure your local server: Even with tunnels, follow security best practices

5. Clean up: Stop tunnels when not in use to free up resources