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

json

{
  "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"
}

Field	Type	Description
id	string	Unique tunnel identifier
name	string	Display name
subdomain	string	URL subdomain (auto-generated or custom)
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.

http

GET /api/tunnels
Authorization: Bearer {token}

Response

json

{
  "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

curlJavaScriptPython

bash

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

javascript

const response = await fetch('https://api.hookbase.app/api/tunnels', {
  headers: {
    'Authorization': 'Bearer whr_your_api_key'
  }
});
const data = await response.json();

python

import requests

response = requests.get(
  'https://api.hookbase.app/api/tunnels',
  headers={'Authorization': 'Bearer whr_your_api_key'}
)
data = response.json()

Get Tunnel

Retrieve details for a specific tunnel.

http

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

Response

json

{
  "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.

http

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)

json

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

Response

json

{
  "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

curlJavaScriptPython

bash

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"}'

javascript

const response = await fetch('https://api.hookbase.app/api/tunnels', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer whr_your_api_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Dev Server'
  })
});
const data = await response.json();

python

import requests

response = requests.post(
  'https://api.hookbase.app/api/tunnels',
  headers={
    'Authorization': 'Bearer whr_your_api_key',
    'Content-Type': 'application/json'
  },
  json={'name': 'Dev Server'}
)
data = response.json()

Update Tunnel

Update tunnel properties.

http

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

Request Body

json

{
  "name": "Updated Name"
}

Response

json

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

Delete Tunnel

Permanently delete a tunnel.

http

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

Response

json

{
  "success": true
}

Get Live Status

Get real-time status information for a tunnel.

http

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

Response

json

{
  "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.

http

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

Response

json

{
  "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.

http

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

Response

json

{
  "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:

json

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

Response to server:

json

{
  "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:

bash

# 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:

bash

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 ​

Overview ​

Endpoints ​

Tunnel Object ​

List Tunnels ​

Response ​

Example ​

Get Tunnel ​

Response ​

Create Tunnel ​

Request Body ​

Response ​

Example ​

Update Tunnel ​

Request Body ​

Response ​

Delete Tunnel ​

Response ​

Get Live Status ​

Response ​

Regenerate Token ​

Response ​

Disconnect Tunnel ​

Response ​

Tunnel URLs ​

WebSocket Connection ​

Message Format ​

Using with the CLI ​

Custom Subdomains ​

Tunnels API

Overview

Endpoints

Tunnel Object

List Tunnels

Response

Example

Get Tunnel

Response

Create Tunnel

Request Body

Response

Example

Update Tunnel

Request Body

Response

Delete Tunnel

Response

Get Live Status

Response

Regenerate Token

Response

Disconnect Tunnel

Response

Tunnel URLs

WebSocket Connection

Message Format

Using with the CLI

Custom Subdomains