Tunnels API

Tunnels allow you to expose local development servers to receive webhooks from the internet. The Hookbase tunnel system provides secure, reliable connections with real-time request logging.

Overview

Each tunnel gets a unique public URL
Tunnels forward HTTP requests to your local server
WebSocket connections enable real-time bidirectional communication
Request logs are captured for debugging

Endpoints

Method	Endpoint	Description
GET	`/api/tunnels`	List all tunnels
GET	`/api/tunnels/{tunnelId}`	Get tunnel details
POST	`/api/tunnels`	Create a new tunnel
PATCH	`/api/tunnels/{tunnelId}`	Update a tunnel
DELETE	`/api/tunnels/{tunnelId}`	Delete a tunnel
GET	`/api/tunnels/{tunnelId}/status`	Get live status
POST	`/api/tunnels/{tunnelId}/regenerate-token`	Regenerate auth token
POST	`/api/tunnels/{tunnelId}/disconnect`	Disconnect tunnel

Tunnel Object

{
  "id": "tun_abc123",
  "name": "Dev Server",
  "subdomain": "cool-sunset-x7kf",
  "direction": "inbound",
  "allowedHosts": [],
  "status": "connected",
  "totalRequests": 142,
  "lastConnectedAt": "2024-01-20T14:30:00Z",
  "createdAt": "2024-01-15T10:00:00Z"
}

Field	Type	Description
id	string	Unique tunnel identifier
name	string	Display name
subdomain	string	URL subdomain (auto-generated or custom)
direction	string	`inbound` (default) or `bidirectional`
allowedHosts	string[]	Allowed target hostnames for bidirectional tunnels (max 20)
status	string	`connected`, `disconnected`, or `error`
totalRequests	number	Total requests forwarded
lastConnectedAt	string	Last connection timestamp
createdAt	string	Creation timestamp

List Tunnels

Get all tunnels for the organization.

GET /api/tunnels
Authorization: Bearer {token}

Response

{
  "tunnels": [
    {
      "id": "tun_abc123",
      "name": "Dev Server",
      "subdomain": "cool-sunset-x7kf",
      "status": "connected",
      "totalRequests": 142,
      "lastConnectedAt": "2024-01-20T14:30:00Z",
      "createdAt": "2024-01-15T10:00:00Z"
    }
  ]
}

Example

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

Get Tunnel

Retrieve details for a specific tunnel.

GET /api/tunnels/{tunnelId}
Authorization: Bearer {token}

Response

{
  "tunnel": {
    "id": "tun_abc123",
    "name": "Dev Server",
    "subdomain": "cool-sunset-x7kf",
    "status": "connected",
    "totalRequests": 142,
    "lastConnectedAt": "2024-01-20T14:30:00Z",
    "createdAt": "2024-01-15T10:00:00Z"
  }
}

Create Tunnel

Create a new tunnel.

POST /api/tunnels
Authorization: Bearer {token}
Content-Type: application/json

Request Body

Field	Type	Required	Description
name	string	Yes	Display name
subdomain	string	No	Custom subdomain (Pro plan only)
direction	string	No	`inbound` (default) or `bidirectional` (Pro/Business)
allowedHosts	string[]	No	Allowed target hostnames for bidirectional tunnels (max 20)

{
  "name": "Dev Server",
  "subdomain": "my-custom-subdomain"
}

Response

{
  "tunnel": {
    "id": "tun_xyz789",
    "name": "Dev Server",
    "subdomain": "my-custom-subdomain",
    "status": "disconnected",
    "totalRequests": 0,
    "createdAt": "2024-01-20T15:00:00Z"
  },
  "tunnelUrl": "https://api.hookbase.app/t/my-custom-subdomain",
  "wsUrl": "wss://api.hookbase.app/tunnels/my-custom-subdomain/ws?tunnelId=tun_xyz789&token=...",
  "authToken": "tunnel_auth_token_here"
}

Example

curl -X POST https://api.hookbase.app/api/tunnels \
  -H "Authorization: Bearer whr_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "Dev Server"}'

Update Tunnel

Update tunnel properties.

PATCH /api/tunnels/{tunnelId}
Authorization: Bearer {token}
Content-Type: application/json

Request Body

{
  "name": "Updated Name"
}

Response

{
  "tunnel": {
    "id": "tun_abc123",
    "name": "Updated Name",
    "subdomain": "cool-sunset-x7kf",
    "status": "connected",
    "totalRequests": 142
  }
}

Delete Tunnel

Permanently delete a tunnel.

DELETE /api/tunnels/{tunnelId}
Authorization: Bearer {token}

Response

{
  "success": true
}

Get Live Status

Get real-time status information for a tunnel.

GET /api/tunnels/{tunnelId}/status
Authorization: Bearer {token}

Response

{
  "tunnel": {
    "id": "tun_abc123",
    "name": "Dev Server",
    "status": "connected"
  },
  "liveStatus": {
    "connected": true,
    "connectedAt": "2024-01-20T14:30:00Z",
    "clientIp": "192.168.1.100",
    "requestsInSession": 42
  }
}

Regenerate Token

Generate a new authentication token for connecting to the tunnel. Use this when you need fresh credentials for a WebSocket connection.

POST /api/tunnels/{tunnelId}/regenerate-token
Authorization: Bearer {token}

Response

{
  "tunnel": {
    "id": "tun_abc123",
    "name": "Dev Server",
    "subdomain": "cool-sunset-x7kf"
  },
  "authToken": "new_auth_token_here",
  "wsUrl": "wss://api.hookbase.app/tunnels/cool-sunset-x7kf/ws?tunnelId=tun_abc123&token=..."
}

Disconnect Tunnel

Force disconnect an active tunnel connection.

POST /api/tunnels/{tunnelId}/disconnect
Authorization: Bearer {token}

Response

{
  "success": true
}

Tunnel URLs

Public tunnel URLs follow this format:

https://api.hookbase.app/t/{subdomain}

For example:

https://api.hookbase.app/t/cool-sunset-x7kf
https://api.hookbase.app/t/my-custom-subdomain

WebSocket Connection

To connect to a tunnel and forward requests, use the WebSocket URL provided when creating the tunnel or regenerating the token:

wss://api.hookbase.app/tunnels/{subdomain}/ws?tunnelId={tunnelId}&token={authToken}

The WebSocket protocol:

Connect: Establish WebSocket connection with auth token
Receive requests: Server sends HTTP requests as JSON messages
Send responses: Client responds with HTTP response data
Heartbeat: Periodic ping/pong to maintain connection

Message Format

Request from server:

{
  "type": "request",
  "id": "req_123",
  "method": "POST",
  "path": "/webhook",
  "headers": {
    "content-type": "application/json"
  },
  "body": "{\"event\":\"push\"}"
}

Response to server:

{
  "type": "response",
  "id": "req_123",
  "status": 200,
  "headers": {
    "content-type": "application/json"
  },
  "body": "{\"received\":true}"
}

Using with the CLI

The easiest way to use tunnels is with the Hookbase CLI:

# Create and connect in one step
hookbase tunnels start 3000
 
# Or create first, then connect
hookbase tunnels create --name "My Tunnel"
hookbase tunnels connect tun_abc123 3000
 
# Monitor with TUI
hookbase tunnels monitor tun_abc123 3000

See CLI Commands for full documentation.

Custom Subdomains

Custom subdomains are available on Pro plans and above:

hookbase tunnels create --name "Production" --subdomain myapp
# URL: https://api.hookbase.app/t/myapp

Requirements:

3-63 characters
Lowercase letters, numbers, and hyphens only
Must start with a letter
Must be unique across all organizations

Tunnels API

Tunnels allow you to expose local development servers to receive webhooks from the internet. The Hookbase tunnel system provides secure, reliable connections with real-time request logging.

Overview

Each tunnel gets a unique public URL
Tunnels forward HTTP requests to your local server
WebSocket connections enable real-time bidirectional communication
Request logs are captured for debugging

Endpoints

Method	Endpoint	Description
GET	`/api/tunnels`	List all tunnels
GET	`/api/tunnels/{tunnelId}`	Get tunnel details
POST	`/api/tunnels`	Create a new tunnel
PATCH	`/api/tunnels/{tunnelId}`	Update a tunnel
DELETE	`/api/tunnels/{tunnelId}`	Delete a tunnel
GET	`/api/tunnels/{tunnelId}/status`	Get live status
POST	`/api/tunnels/{tunnelId}/regenerate-token`	Regenerate auth token
POST	`/api/tunnels/{tunnelId}/disconnect`	Disconnect tunnel

Tunnel Object

{
  "id": "tun_abc123",
  "name": "Dev Server",
  "subdomain": "cool-sunset-x7kf",
  "direction": "inbound",
  "allowedHosts": [],
  "status": "connected",
  "totalRequests": 142,
  "lastConnectedAt": "2024-01-20T14:30:00Z",
  "createdAt": "2024-01-15T10:00:00Z"
}

Field	Type	Description
id	string	Unique tunnel identifier
name	string	Display name
subdomain	string	URL subdomain (auto-generated or custom)
direction	string	`inbound` (default) or `bidirectional`
allowedHosts	string[]	Allowed target hostnames for bidirectional tunnels (max 20)
status	string	`connected`, `disconnected`, or `error`
totalRequests	number	Total requests forwarded
lastConnectedAt	string	Last connection timestamp
createdAt	string	Creation timestamp

List Tunnels

Get all tunnels for the organization.

GET /api/tunnels
Authorization: Bearer {token}

Response

{
  "tunnels": [
    {
      "id": "tun_abc123",
      "name": "Dev Server",
      "subdomain": "cool-sunset-x7kf",
      "status": "connected",
      "totalRequests": 142,
      "lastConnectedAt": "2024-01-20T14:30:00Z",
      "createdAt": "2024-01-15T10:00:00Z"
    }
  ]
}

Example

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

Get Tunnel

Retrieve details for a specific tunnel.

GET /api/tunnels/{tunnelId}
Authorization: Bearer {token}

Response

{
  "tunnel": {
    "id": "tun_abc123",
    "name": "Dev Server",
    "subdomain": "cool-sunset-x7kf",
    "status": "connected",
    "totalRequests": 142,
    "lastConnectedAt": "2024-01-20T14:30:00Z",
    "createdAt": "2024-01-15T10:00:00Z"
  }
}

Create Tunnel

Create a new tunnel.

POST /api/tunnels
Authorization: Bearer {token}
Content-Type: application/json

Request Body

Field	Type	Required	Description
name	string	Yes	Display name
subdomain	string	No	Custom subdomain (Pro plan only)
direction	string	No	`inbound` (default) or `bidirectional` (Pro/Business)
allowedHosts	string[]	No	Allowed target hostnames for bidirectional tunnels (max 20)

{
  "name": "Dev Server",
  "subdomain": "my-custom-subdomain"
}

Response

{
  "tunnel": {
    "id": "tun_xyz789",
    "name": "Dev Server",
    "subdomain": "my-custom-subdomain",
    "status": "disconnected",
    "totalRequests": 0,
    "createdAt": "2024-01-20T15:00:00Z"
  },
  "tunnelUrl": "https://api.hookbase.app/t/my-custom-subdomain",
  "wsUrl": "wss://api.hookbase.app/tunnels/my-custom-subdomain/ws?tunnelId=tun_xyz789&token=...",
  "authToken": "tunnel_auth_token_here"
}

Example

curl -X POST https://api.hookbase.app/api/tunnels \
  -H "Authorization: Bearer whr_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "Dev Server"}'

Update Tunnel

Update tunnel properties.

PATCH /api/tunnels/{tunnelId}
Authorization: Bearer {token}
Content-Type: application/json

Request Body

{
  "name": "Updated Name"
}

Response

{
  "tunnel": {
    "id": "tun_abc123",
    "name": "Updated Name",
    "subdomain": "cool-sunset-x7kf",
    "status": "connected",
    "totalRequests": 142
  }
}

Delete Tunnel

Permanently delete a tunnel.

DELETE /api/tunnels/{tunnelId}
Authorization: Bearer {token}

Response

{
  "success": true
}

Get Live Status

Get real-time status information for a tunnel.

GET /api/tunnels/{tunnelId}/status
Authorization: Bearer {token}

Response

{
  "tunnel": {
    "id": "tun_abc123",
    "name": "Dev Server",
    "status": "connected"
  },
  "liveStatus": {
    "connected": true,
    "connectedAt": "2024-01-20T14:30:00Z",
    "clientIp": "192.168.1.100",
    "requestsInSession": 42
  }
}

Regenerate Token

Generate a new authentication token for connecting to the tunnel. Use this when you need fresh credentials for a WebSocket connection.

POST /api/tunnels/{tunnelId}/regenerate-token
Authorization: Bearer {token}

Response

{
  "tunnel": {
    "id": "tun_abc123",
    "name": "Dev Server",
    "subdomain": "cool-sunset-x7kf"
  },
  "authToken": "new_auth_token_here",
  "wsUrl": "wss://api.hookbase.app/tunnels/cool-sunset-x7kf/ws?tunnelId=tun_abc123&token=..."
}

Disconnect Tunnel

Force disconnect an active tunnel connection.

POST /api/tunnels/{tunnelId}/disconnect
Authorization: Bearer {token}

Response

{
  "success": true
}

Tunnel URLs

Public tunnel URLs follow this format:

https://api.hookbase.app/t/{subdomain}

For example:

https://api.hookbase.app/t/cool-sunset-x7kf
https://api.hookbase.app/t/my-custom-subdomain

WebSocket Connection

To connect to a tunnel and forward requests, use the WebSocket URL provided when creating the tunnel or regenerating the token:

wss://api.hookbase.app/tunnels/{subdomain}/ws?tunnelId={tunnelId}&token={authToken}

The WebSocket protocol:

Connect: Establish WebSocket connection with auth token
Receive requests: Server sends HTTP requests as JSON messages
Send responses: Client responds with HTTP response data
Heartbeat: Periodic ping/pong to maintain connection

Message Format

Request from server:

{
  "type": "request",
  "id": "req_123",
  "method": "POST",
  "path": "/webhook",
  "headers": {
    "content-type": "application/json"
  },
  "body": "{\"event\":\"push\"}"
}

Response to server:

{
  "type": "response",
  "id": "req_123",
  "status": 200,
  "headers": {
    "content-type": "application/json"
  },
  "body": "{\"received\":true}"
}

Using with the CLI

The easiest way to use tunnels is with the Hookbase CLI:

# Create and connect in one step
hookbase tunnels start 3000
 
# Or create first, then connect
hookbase tunnels create --name "My Tunnel"
hookbase tunnels connect tun_abc123 3000
 
# Monitor with TUI
hookbase tunnels monitor tun_abc123 3000

See CLI Commands for full documentation.

Custom Subdomains

Custom subdomains are available on Pro plans and above:

hookbase tunnels create --name "Production" --subdomain myapp
# URL: https://api.hookbase.app/t/myapp

Requirements:

3-63 characters
Lowercase letters, numbers, and hyphens only
Must start with a letter
Must be unique across all organizations