CLI

The HookSense CLI forwards webhooks captured by your cloud endpoint to a process running on your machine. Unlike a tunnel (ngrok, cloudflared) it pulls events over HTTPS from HookSense — no inbound port exposure, no auth tokens to manage.

Installation

Run directly with npx (no install needed):

npx hooksense listen -p 3000

Or install globally for shorter invocations and faster cold start:

npm install -g hooksense
hooksense listen -p 3000

Requires Node.js 18 or newer. The CLI is a separate package — source: github.com/ozers/hooksense-cli.

Quick Start

1. Create a HookSense endpoint (https://hooksense.com/w/your-slug)
2. Start your local server on any port (e.g., localhost:3000)
3. Run npx hooksense listen -p 3000
4. Send a webhook to your HookSense URL — it appears in HookSense AND on your local server within milliseconds

Common Workflows

Forward to a Specific Path

npx hooksense listen -p 3000 --path /webhooks/stripe

Webhooks are POSTed to http://localhost:3000/webhooks/stripe with the original method, headers, and body preserved.

Target a Specific Endpoint

If you have several endpoints, forward only one:

npx hooksense listen --endpoint my-stripe-hook -p 3000

Without --endpoint, the CLI prompts you to pick from your account's endpoints.

Custom Forward URL

Forward somewhere other than localhost — e.g., a Docker service or a teammate's machine on a tailnet:

npx hooksense listen --forward http://api.local:3000/webhooks

Stripe-Style Workflow

Replace stripe listen --forward-to localhost:3000/webhooks with HookSense for the same shape but persistent URLs and replay history:

npx hooksense listen -p 3000 --path /webhooks/stripe

Authentication

Anonymous CLI sessions use the free tier limits (300 req/day shared with anonymous endpoints). Link your account to use your plan's limits:

npx hooksense login

The browser opens for OAuth; the CLI stores a token in ~/.config/hooksense/credentials.json. Log out with hooksense logout any time.

Output & Logging

Each forwarded request prints a one-line summary:

POST /webhooks/stripe  →  200 OK  (12ms)

Add --verbose to see full headers and body. Add --quiet to suppress output (useful in CI).

Exit Codes

Code	Meaning
0	Clean shutdown (Ctrl+C)
1	Generic error (network, auth, etc.)
2	Invalid arguments or missing endpoint
3	Authentication failed or session expired

Troubleshooting

• "Connection refused" on forward — your local server isn't listening on the port you passed; verify with curl localhost:PORT.
• "401 Unauthorized" from HookSense — run npx hooksense login again; tokens expire after 30 days of inactivity.
• CLI hangs on startup — check firewall/proxy egress to hooksense.com:443; the CLI uses HTTPS, not WebSockets.
• Some webhooks missing — check rate limits in the dashboard; daily quota applies to CLI forwarding too.