🎣 Hooktunnel CLI (tsuu)

🚀 What is Hooktunnel?

Hooktunnel (tsuu) is a developer tool that solves the webhook testing problem. It creates secure tunnels to forward webhooks from production services (Stripe, GitHub, Shopify, etc.) directly to your local development environment — or even to remote staging/production servers for integration testing.

Think ngrok, but specialized for webhooks with bidirectional forwarding capabilities.

Why "tsuu" (通)?

The Japanese character 通 (tsuu) means "to pass through" or "to transmit" — exactly what this tool does with your webhooks. It also means "expert" or "connoisseur," reflecting developers who master webhook integration.

✨ Features

• 🔄 Bidirectional Forwarding — Forward webhooks both inbound (cloud → localhost) and outbound (localhost → production)
• 🎯 Multiple Endpoints — Manage different webhook sources separately
• 🔐 Secure Authentication — API key-based authentication with encrypted storage
• 📊 Beautiful CLI Output — Color-coded logs, status badges, and real-time statistics
• ⚡ WebSocket Connection — Real-time webhook delivery with automatic reconnection
• 🎨 Developer Experience First — Intuitive commands, helpful error messages, detailed logging
• 🔍 Request Inspection — See full headers, payloads, and response times
• 📈 Performance Metrics — Track success rates, response times, and request counts
• 🌐 Flexible Routing — Override target URLs per connection for testing different environments

📦 Installation

Via bun (Recommended)

bun install -g @hooktunnel/tsuu

Via npm

npm install -g @hooktunnel/tsuu

Via yarn

yarn global add @hooktunnel/tsuu

Via pnpm

pnpm add -g @hooktunnel/tsuu

🎯 Quick Start

1. Create an Account

Visit hooktunnel.dev and sign up for a free account.

2. Generate an API Key

Go to your API Keys Dashboard and create a new key.

3. Authenticate CLI

tsuu login

Paste your API key when prompted (format: whl_...).

4. Create an Endpoint

In the Hooktunnel dashboard, create a new endpoint and configure:

• Name: e.g., "Stripe Webhooks"
• Slug: e.g., "stripe-webhooks"
• Target URL: e.g., "api/webhooks/stripe"

5. Start Forwarding

tsuu connect --port 3000 --endpoint stripe-webhooks

6. Use Your Relay URL

Configure your webhook provider to send webhooks to:

https://hooktunnel.dev/r/<your-user-id>/stripe-webhooks

That's it! Webhooks will now flow through Hooktunnel to your localhost. 🎉

📖 Usage

Commands

tsuu login

Authenticate with your Hooktunnel account.

tsuu login

What it does:

• Prompts for your API key
• Validates the key with Hooktunnel servers
• Stores credentials securely in ~/.hooktunnel/config.json

tsuu connect

Start the webhook tunnel and forward requests to your local or remote server.

tsuu connect [options]

Options:

| Option | Alias | Description | Default | | ------------------- | ----- | ----------------------------------------- | ---------------------------- | | --port <port> | -p | Port to forward webhooks to | `` | | --endpoint <slug> | -e | Specific endpoint to listen to | All endpoints | | --target <path> | -t | Override target path from endpoint config | Endpoint's configured target | | --host <host> | -h | Custom host to forward to | http://localhost |

Examples:

# Connect to all endpoints on port 3000
tsuu connect --port 3000

# Connect to specific endpoint
tsuu connect --endpoint stripe-webhooks --port 8080

# Override target URL for testing
tsuu connect --endpoint stripe-webhooks --target api/v2/webhooks --port 3000

# Forward to remote server instead of localhost
tsuu connect --host https://staging.myapp.com --endpoint github-webhooks

tsuu list

Display all configured endpoints in your account.

tsuu list

Output includes:

• Endpoint name and slug
• Relay URL for webhook providers
• Active/inactive status
• Number of webhooks received today

tsuu help

Show comprehensive help with examples.

tsuu help

🎪 Use Cases

1. Local Webhook Development

Test Stripe, PayPal, or any webhook integration locally without deploying:

# Start your local server
npm run dev

# In another terminal, start hooktunnel
tsuu connect --port 3000 --endpoint stripe-webhooks

# Configure Stripe to send webhooks to your relay URL
# https://hooktunnel.dev/r/<user-id>/stripe-webhooks

2. Production Integration Testing

Forward webhooks from localhost to your staging/production API:

# Test how production will handle webhooks
tsuu connect --host https://api.production.com --endpoint test-integration

3. Multi-Environment Testing

Test the same webhook across different environments:

# Terminal 1: Dev
tsuu connect --port 3000 --endpoint shopify

# Terminal 2: Staging
tsuu connect --host https://staging.myapp.com --endpoint shopify

# Terminal 3: Production
tsuu connect --host https://api.myapp.com --endpoint shopify

4. Debugging Production Issues

Replay production webhooks locally to debug:

# View webhook history in dashboard, then forward to local
tsuu connect --port 3000 --endpoint production-webhooks

🎨 CLI Output Examples

Successful Connection

✨ Connected to hooktunnel

╭────────────────────────────────────────────────────────────╮
│ Connection Details                                         │
│                                                            │
│ 📍 Endpoint:     stripe-webhooks                          │
│ 🔗 Relay URL:    https://hooktunnel.dev/r/user123/stripe │
│ 🎯 Forwarding:   http://localhost:3000/api/webhooks      │
│ 👤 User:         [email protected]                          │
╰────────────────────────────────────────────────────────────╯

✓ Ready to receive webhooks
  Press Ctrl+C to stop

Webhook Reception

 🎣 INCOMING WEBHOOK  at 14:32:15
┌──────────────────────────────────────────────────────────┐
│  POST  /api/webhooks/stripe
│ → http://localhost:3000/api/webhooks/stripe
│
│ ←  200  42ms (OK)
│    Size: 1.23 KB
└──────────────────────────────────────────────────────────┘

Statistics Display

────────────────────────────────────────────────────────────
📊 Stats: 47 requests │ 45 success │ 2 failed │ 95.7% success rate │ 38ms avg │ 142s uptime
────────────────────────────────────────────────────────────

🔧 Configuration

Configuration is stored in ~/.hooktunnel/config.json:

{
  "apiKey": "whl_xxxxxxxxxxxxxxxxxxxxx",
  "user": {
    "id": "user_123456",
    "email": "[email protected]"
  },
  "authenticatedAt": "2024-11-18T10:30:00.000Z"
}

File Permissions: Automatically set to 0600 (read/write for owner only) for security.

🐛 Troubleshooting

Authentication Failed

Problem: API key not recognized

Solutions:

1. Verify you copied the complete API key (starts with whl_)
2. Generate a new key at dashboard/api-keys
3. Check that the key hasn't been revoked

Connection Failed

Problem: Cannot connect to hooktunnel server

Solutions:

1. Check your internet connection
2. Verify the hooktunnel server is online
3. Check firewall settings (WebSocket port may be blocked)
4. Try reconnecting: tsuu connect

Webhooks Not Forwarding

Problem: Connected but webhooks aren't reaching localhost

Solutions:

1. Verify your local server is running on the specified port
2. Check that the target URL path is correct
3. Review endpoint configuration in the dashboard
4. Look for errors in the CLI output

Invalid API Key Format

Problem: "Invalid API key format" error

Solution: Ensure the API key starts with whl_ — this is the required prefix.

🏗️ Architecture

┌─────────────────┐
│ Webhook Provider│
│  (Stripe, etc.) │
└────────┬────────┘
         │ HTTPS
         ▼
┌─────────────────────────────┐
│   Hooktunnel Cloud Server   │
│  (hooktunnel.dev)           │
└────────┬────────────────────┘
         │ WebSocket
         ▼
┌─────────────────┐
│   tsuu CLI      │
│  (Your Machine) │
└────────┬────────┘
         │ HTTP
         ▼
┌─────────────────┐
│  Local Server   │
│  or Remote API  │
└─────────────────┘

🎯 What Makes Hooktunnel Different

Hooktunnel is purpose-built for webhook development, offering features specifically designed for this use case:

• Webhook-First Design - Built specifically for webhook testing workflows
• Bidirectional Forwarding - Test both receiving and sending webhooks
• Multiple Named Endpoints - Organize different webhook sources separately
• Beautiful Developer Experience - Color-coded logs, real-time stats, intuitive CLI
• Webhook History & Replay - Review and resend past webhooks (Web UI)
• Flexible Routing - Forward to localhost or remote servers dynamically

When to Use Hooktunnel

Use Hooktunnel when:

• You're primarily testing webhooks (Stripe, GitHub, Shopify, etc.)
• You need to manage multiple webhook endpoints
• You want beautiful, informative CLI output
• You need to test webhook flows in different environments

📝 License

MIT License - see LICENSE for details

🔗 Links

• 🌐 Website: hooktunnel.dev
• 📚 Documentation: hooktunnel.dev/docs

💡 Tips & Tricks

Multiple Terminals for Different Endpoints

Run multiple instances simultaneously:

# Terminal 1: Stripe webhooks
tsuu connect --endpoint stripe --port 3000

# Terminal 2: GitHub webhooks
tsuu connect --endpoint github --port 4000

# Terminal 3: Shopify webhooks
tsuu connect --endpoint shopify --port 5000

Testing Error Handling

Use the target override to send webhooks to a broken endpoint:

tsuu connect --target api/broken-endpoint --port 3000

Quick Local Testing

No endpoint configured yet? Connect to all endpoints:

tsuu connect --port 3000