Tunneling & CLI

The CatchHook CLI provides a fast-ack local relay over a WebSocket connection so you can debug against localhost without deploying.

CatchHook captures the request and returns the endpoint's configured response to the provider before local delivery completes. The CLI then sends the captured request to your local URL and reports the local status and timing separately. The local response is not returned to the webhook provider.

Permanent endpoints require a paid account. Temporary endpoints can tunnel without login.

How it works

1. The CatchHook CLI opens a WebSocket connection to CatchHook.
2. CatchHook captures an incoming event and acknowledges the provider.
3. The saved event is streamed to the CLI.
4. The CLI delivers it to your local URL.
5. The CLI reports local delivery results back to CatchHook for metrics and alerts.

Webhook events are forwarded with the original HTTP method, headers, and body.

Permanent endpoint flow

Use start directly. If no valid token is stored, the CLI opens browser auth automatically.

npx @catchhook/tunnel start --endpoint ep_abc123 --port 3000

Headless alternatives:

# One-off
npx @catchhook/tunnel start --endpoint ep_abc123 --port 3000 --token chk_dev_xxx

# Environment
CATCHHOOK_TOKEN=chk_dev_xxx npx @catchhook/tunnel start --endpoint ep_abc123 --port 3000

Temporary endpoint flow

Temporary endpoints include a tunnel_key:

npx @catchhook/tunnel ep_abc123 --key tkey_abc123 --port 3000

No account login required.

Provider presets

Use --provider to get provider-aware setup, signature verification, and richer event display:

# Create a new endpoint preconfigured for GitHub
npx @catchhook/tunnel start --provider github --port 3000

# Attach GitHub provider config to an existing endpoint
npx @catchhook/tunnel start --provider github --endpoint ep_abc123

Supported providers: github, stripe.

When --provider is used:

• New endpoint — the CLI creates an endpoint with provider metadata, generates a webhook signing secret, creates a signature verification config, and shows setup instructions (where to paste the URL and secret in the provider's dashboard).
• Existing endpoint — the CLI creates a signature config for that endpoint. If one already exists, it prompts before overwriting.
• Anonymous/temporary — full provider setup works with --key too, including signature config and setup instructions.
• Target URL — when the target is a port or omitted, the CLI appends the provider's default path (e.g., /webhooks/github). Full URLs are used as-is.

Restrictions:

• --provider with --all is not supported.
• --provider with multiple --endpoint values is not supported.

Incoming webhooks on all endpoints are automatically analyzed for provider detection. When a known provider is detected (from headers or body), the dashboard and CLI show the provider name, event type (e.g., "GitHub push" or "Stripe invoice.paid"), and replay warnings for dangerous events. This works regardless of whether --provider was used.

Active connections

The Tunnel tab on each endpoint shows a table of active connections with:

• User — the signed-in user (or "Anonymous" for temporary endpoints).
• Target — the local URL where the CLI delivers events.
• Client — hostname, OS, and CLI version reported by the connected client.
• Connected since — how long the connection has been open.
• Status — Healthy (heartbeat within the last minute) or Stale.

Delivery gaps and recovery

Authenticated permanent endpoints remember that they are expected to be tunneling. If a webhook arrives while the monitored tunnel is disconnected, CatchHook:

1. captures the webhook normally;
2. records one durable delivery gap for the outage;
3. notifies the endpoint's workspace through email, Slack, or a generic webhook; and
4. offers deliberate recovery the next time the CLI connects.

The existing short-window catch-up remains automatic. Longer durable gaps use the --catch-up safety modes:

# Recover every retained request without an interactive prompt
npx @catchhook/tunnel start --endpoint ep_abc123 --catch-up all

# Start live delivery only
npx @catchhook/tunnel start --endpoint ep_abc123 --catch-up none

Recovery always sends to the current command target. The CLI displays a historical target when it differs, records every local delivery result, and leaves failed or expired requests marked as partial rather than claiming the gap was recovered.

The Tunnel panel contains the monitoring toggle, outage boundary, retained missed count, recovery status, and an explicit dismiss action. Disabling monitoring prevents future gaps without deleting history.

Authentication model

• CLI auth creates a token scoped for tunneling and reads.
• CLI tokens expire after 30 days.
• Re-authenticating revokes older CLI tokens for that user/account.
• Browser callback uses a one-time auth code exchanged for the token by the CLI.

Connection limits

Troubleshooting