Listen Mode
The listen command forwards webhooks from an existing Hooklistener endpoint to your local server in real time. It opens a WebSocket connection and displays incoming requests in an interactive terminal UI (TUI).
Basic usage
# Forward to localhost:3000 (default)
hooklistener listen my-endpoint
# Forward to a custom URL
hooklistener listen my-endpoint --target http://localhost:8080
Options
| Flag | Short | Default | Description |
|---|---|---|---|
--target | -t | http://localhost:3000 | Local URL to forward requests to |
--ws-url | — | Production server | WebSocket server URL (for self-hosting) |
Interactive TUI
The listen command opens an interactive terminal interface with three views.
Request list
The main view shows all incoming requests:
| Key | Action |
|---|---|
↑ / ↓ | Navigate request list |
Enter | View request details |
/ | Activate search mode |
q / Esc | Quit |
Search mode
Press / to search. Searches across method, URL, path, body preview, and remote address.
| Key | Action |
|---|---|
| Type text | Enter search query |
Enter | Confirm search |
Backspace | Delete character |
Esc | Exit search |
Request detail view
Press Enter on a request to see full details with three tabs:
| Tab | Content |
|---|---|
| Info | Method, URL, remote IP, timestamp, content length, request ID |
| Headers | Scrollable list of all request headers |
| Body | Syntax-highlighted body (JSON formatting when applicable) |
Navigation:
| Key | Action |
|---|---|
Tab / → | Next tab |
Shift+Tab / ← | Previous tab |
↑ / ↓ / j / k | Scroll content |
PageUp / PageDown | Page scroll |
Home / End | Jump to top/bottom |
f | Enter forward URL input |
r | Replay request with last forward URL |
e | Open export menu |
b / Esc | Back to list |
q | Quit |
Export menu
Press e in the detail view to export:
| Key | Action |
|---|---|
1 / c | Copy as cURL command |
2 / j | Copy as JSON |
Esc | Cancel |
Connection behavior
- Auto-reconnect — automatically reconnects on connection drops with exponential backoff (up to 10 retries)
- Heartbeat — sends a ping every 30 seconds to keep the connection alive
- Real-time — requests appear in the TUI within milliseconds of arrival
Example workflow
# 1. Start your local server
npm run dev # or whatever starts your app on port 3000
# 2. Forward webhooks to it
hooklistener listen stripe-webhooks --target http://localhost:3000/api/webhooks
# 3. Trigger a webhook from your provider (e.g., Stripe)
# 4. See it appear in the TUI and hit your local server