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 ──▶ Hookbase Tunnel ──▶ Your Local Server
     (GitHub)           (*.tunnel.hookbase.app)        (localhost:3000)

How It Works

1. Start the tunnel client on your local machine
2. Get a public URL (e.g., abc123.tunnel.hookbase.app)
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 @hookbase/cli
 
# or download binary
curl -fsSL https://get.hookbase.app | sh

2. Login

hookbase login

3. Start a Tunnel

# Forward to localhost:3000
hookbase tunnel --port 3000
 
# With custom subdomain (paid plans)
hookbase tunnel --port 3000 --subdomain myapp

Output:

Tunnel established!
Public URL: https://abc123.tunnel.hookbase.app
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
hookbase tunnel --port 3000
 
# Custom local host
hookbase tunnel --port 3000 --host 127.0.0.1
 
# Custom subdomain (requires paid plan)
hookbase tunnel --port 3000 --subdomain myapp
 
# Forward to HTTPS locally
hookbase tunnel --port 443 --local-https

List Active Tunnels

hookbase tunnels list

Stop Tunnel

# Stop by subdomain
hookbase tunnel stop abc123
 
# Stop all
hookbase 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

Request Inspection

Enable inspection to see all requests passing through the tunnel:

hookbase 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.hookbase.app/api/tunnels \
  -H "Authorization: Bearer whr_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "subdomain": "myapp",
    "targetPort": 3000
  }'

List Tunnels

curl https://api.hookbase.app/api/tunnels \
  -H "Authorization: Bearer whr_your_api_key"

Delete Tunnel

curl -X DELETE https://api.hookbase.app/api/tunnels/{tunnelId} \
  -H "Authorization: Bearer whr_your_api_key"

Use Cases

Local Development

Test webhook integrations without deploying:

# Start your local server
npm run dev  # localhost:3000
 
# In another terminal, start the tunnel
hookbase tunnel --port 3000
 
# Configure GitHub to send webhooks to your tunnel URL

Demo Environments

Create temporary public URLs for demos:

hookbase tunnel --port 8080 --subdomain demo
# https://demo.tunnel.hookbase.app

Testing CI/CD

Test webhook-triggered pipelines locally:

hookbase 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

Troubleshooting

Tunnel not connecting

1. Check your internet connection
2. Verify you're logged in: hookbase 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

Bidirectional Tunnels

Standard tunnels are inbound-only: they forward external requests to your local machine. Bidirectional tunnels add outbound proxy support, allowing your local applications to make HTTP requests through Hookbase to external services.

Use Cases

• Access internal APIs or IoT devices behind firewalls
• Route outbound requests through Hookbase's infrastructure
• Test integrations with external services from local development

Creating a Bidirectional Tunnel

In the dashboard, select Bidirectional when creating a tunnel. Optionally specify allowed target hosts.

Via API:

curl -X POST https://api.hookbase.app/api/organizations/{orgId}/tunnels \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Dev Tunnel",
    "direction": "bidirectional",
    "allowedHosts": ["api.internal.company.io", "iot-gateway.local"]
  }'

Allowed Hosts

For security, bidirectional tunnels can restrict which external hosts the proxy can reach. If allowedHosts is empty, all hosts are allowed.

How Outbound Proxy Works

Local App → CLI (localhost:9090) → WebSocket → Hookbase DO → External Service
                                 ← WebSocket ← Hookbase DO ←

1. Your local app sends a request to the CLI's proxy endpoint
2. The CLI forwards it as an outbound_request over the existing WebSocket
3. Hookbase validates the target host against allowedHosts
4. Hookbase makes the outbound HTTP request
5. The response is sent back to your local app via the CLI

Requirements

• Plan: Pro or Business
• CLI: Use hookbase tunnel --bidirectional flag
• Max allowed hosts: 20 per tunnel

See Also

• Tunnels API — Full API reference
• CLI — Manage tunnels from the command line
• Quick Start — Set up your first webhook pipeline
• Testing — Test webhook integrations