hooktunnel-cli

HookTunnel CLI

Webhook infrastructure that never drops a request.

Webhooks are the weakest link in every platform integration. HookTunnel fixes that — reliable ingress, full history, instant replay. For development and production.

npx hooktunnel-cli connect dev 3000

The Problem

Webhooks are fire-and-forget. When they fail, you're blind.

Provider ──────────────────────────────────▶ Your Server
              If down, webhook lost forever       💀

Every team hits these:

Failure Mode	What Happens
Server down	Webhook gone. Stripe retries 8x, GitHub gives you 1 shot.
Handler bug	You need the exact payload to debug. It's gone.
URL changed	Redeployed? New infra? Webhooks silently fail.
No visibility	Something broke. What was in that payload? Who knows.
Can't replay	Fixed the bug, but need to wait for a real event to test.

Traditional tools don't solve this:

Tool	Problem
ngrok	URL changes on restart. Dev only. No history.
localtunnel	Unstable. No persistence. Dev only.
RequestBin	View-only. Can't forward or replay.
Custom logging	You built it. You maintain it. It's missing features.

The Solution

HookTunnel is infrastructure between providers and your servers.

              WITHOUT                              WITH HOOKTUNNEL

Provider ────────▶ Your Server        Provider ────▶ HookTunnel ────▶ Your Server
        (if down, lost)                            (always on)      (can be down)
                                                    ✓ Captured       ✓ Process later
                                                    ✓ Logged         ✓ Debug anytime
                                                    ✓ Replayable     ✓ Test fixes
                                                    ✓ Stable URL     ✓ Redeploy freely

What you get:

• Stable URLs — Configure once in Stripe/Twilio/GitHub. Never change again.
• Never lose webhooks — Captured even when your server is down.
• Full history — See every request. Search by content. Debug with context.
• Instant replay — Re-send any webhook to test your fix. No waiting.
• Local forwarding — Forward to localhost for development.

Use Cases

Development: Forward to Localhost

Test against real webhooks while building:

# Terminal 1: Your server
npm run dev

# Terminal 2: Forward webhooks to localhost
hooktunnel connect dev 3000

Every Stripe/Twilio webhook instantly hits your local machine.

Production: Debug Incidents

2am. Payments are failing. What's in those webhooks?

# See what's hitting your webhook endpoint
hooktunnel logs abc123 --limit 50

# Find the problematic request
# Note the log ID of the 500 error

# After fixing, replay to verify
hooktunnel replay log_xyz123 --to https://your-server.com/webhook

Recovery: Server Was Down

Your server crashed for 10 minutes. Providers sent webhooks. They're not lost.

# See what came in while you were down
hooktunnel logs abc123 --limit 100

# Everything is there
# Process them now, or replay to your recovered server

AI-Assisted Debugging

Use with Claude Code for intelligent troubleshooting:

Prompt: "Use hooktunnel to find recent webhook errors and explain what's wrong"

# Claude runs:
hooktunnel logs abc123 --limit 20

# Analyzes the 500 errors
# Explains what payload caused failure
# Suggests fixes

Prompt: "Replay the failed payment webhook and debug my handler"

# Claude runs:
hooktunnel replay log_abc123 --to http://localhost:3000

# Shows the response
# Explains the error
# Helps you fix it

Quick Start

1. Get Your Free Account

# Go to hooktunnel.com
# Sign up (or sign in with GitHub)
# Generate a webhook URL

2. Get Your API Key

# Go to hooktunnel.com/app/settings
# Generate an API key

3. Connect

# Install and login
npx hooktunnel-cli login --key ht_your_api_key

# Start forwarding to localhost:3000
npx hooktunnel-cli connect dev 3000

4. Configure Your Provider

Add your HookTunnel URL to Stripe/Twilio/GitHub webhook settings:

https://hooks.hooktunnel.com/h/your-hook-id

Done. Webhooks flow through HookTunnel to your server.

Installation

# Use directly with npx (recommended)
npx hooktunnel-cli <command>

# Or install globally
npm install -g hooktunnel-cli
hooktunnel <command>

Requirements: Node.js 18+

Commands

hooktunnel login

Authenticate with your API key.

hooktunnel login --key ht_abc123...

Get your API key from hooktunnel.com/app/settings

hooktunnel connect <env> <port>

Forward webhooks to your local server.

# Basic usage
hooktunnel connect dev 3000

# Custom host
hooktunnel connect dev 3000 --host 127.0.0.1

# Verbose mode (shows all request details)
hooktunnel connect dev 3000 --verbose

Output:

🔗 HookTunnel
  Environment: dev
  Local port: 3000

✓ Connected to HookTunnel
  Session: abc12345...
  Forwarding to: http://localhost:3000

Waiting for webhooks... (Ctrl+C to stop)

[12:00:01] POST   /webhook    200  (45ms)
[12:00:05] POST   /webhook    500  (12ms)

Environments:

• dev - Development
• staging - Staging
• prod - Production

hooktunnel hooks

List your webhook endpoints.

hooktunnel hooks

Output:

📌 Your Hooks (2)

  ID                      Provider    Status    Requests
  ------------------------------------------------------------
  abc123def456ghi789      stripe      active    142
  xyz789abc123def456      twilio      active    57

  Webhook URL: https://hooks.hooktunnel.com/h/<hook_id>

hooktunnel logs <hookId>

View request history for a hook.

# Last 20 requests
hooktunnel logs abc123def456

# Last 100 requests
hooktunnel logs abc123def456 --limit 100

Output:

📋 Request Logs for abc123def456... (20)

  Time                Method  Path                          Status  Size
  ---------------------------------------------------------------------------
  1/11/2026 12:00:05  POST    /webhook                      200     1.2KB
  1/11/2026 11:58:32  POST    /webhook                      500     0.8KB

  Log ID (for replay): log_abc123...

hooktunnel replay <logId> (Pro)

Re-send a captured webhook.

# Replay to connected tunnel
hooktunnel replay log_abc123

# Replay to specific URL (including production)
hooktunnel replay log_abc123 --to https://your-server.com/webhook

hooktunnel status

Check your connection and account status.

hooktunnel status

hooktunnel logout

Clear stored credentials.

hooktunnel logout

How It Works

┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│                 │     │                  │     │                 │
│  Stripe/Twilio  │────▶│   HookTunnel     │────▶│  Your Server    │
│  GitHub/etc     │     │   (always on)    │     │  (or CLI)       │
│                 │     │                  │     │                 │
└─────────────────┘     └──────────────────┘     └─────────────────┘
                               │
                               ▼
                        ┌──────────────────┐
                        │  Request History │
                        │  • Full payloads │
                        │  • Searchable    │
                        │  • Replayable    │
                        └──────────────────┘

• Provider sends webhook to your stable HookTunnel URL
• HookTunnel captures and logs — stored even if your server is down
• Request forwarded to your server (or CLI for local dev)
• Full history available — debug, search, replay anytime

The URL never changes. No webhook is ever lost.

Pricing

Feature	Free	Pro ($19/mo)
Webhook URLs	1	10
Requests/day	100	Unlimited
History	24 hours	30 days
CLI Access	✓	✓
Request Replay	-	✓
Payload Storage	-	✓

Start free: hooktunnel.com

Configuration

Credentials stored in:

• Linux/macOS: ~/.config/hooktunnel-cli/config.json
• Windows: %APPDATA%/hooktunnel-cli/config.json

Troubleshooting

"Authentication required"

hooktunnel login --key <your-api-key>

"Connection failed"

• Check internet connection
• Verify API key: hooktunnel status
• Try verbose mode: hooktunnel connect dev 3000 --verbose

502 errors in terminal

Your local server isn't responding:

• Make sure it's running
• Check the port number
• Verify it's listening on localhost

"Pro tier required"

Replay requires Pro. Upgrade at hooktunnel.com/#pricing

Links

• Website: hooktunnel.com
• Dashboard: hooktunnel.com/app
• Documentation: hulupeep.github.io/hooktunnel-help
• Issues: github.com/Hulupeep/hooktunnel-cli/issues

License

MIT