listen Command
Forward webhooks to localhost without changing the provider URL
To forward webhooks to localhost from the command line without changing your provider's URL, point the provider at a hosted Hooklistener endpoint and run hooklistener listen YOUR_ENDPOINT_SLUG --target http://localhost:3000, replacing YOUR_ENDPOINT_SLUG with the endpoint's slug from your dashboard. The CLI forwards each captured request to your local server, and requests that arrive while you're offline stay in history for replay.
npm i -g hooklistener # or: brew tap hooklistener/tap && brew install hooklistener
hooklistener login # one-time browser sign-in
# Replace YOUR_ENDPOINT_SLUG with your endpoint's slug from the dashboard
hooklistener listen YOUR_ENDPOINT_SLUG --target http://localhost:3000
# Each request to your hosted endpoint → http://localhost:3000The listen command forwards webhooks from an existing Hooklistener endpoint to your local development server. This is perfect for debugging production webhooks locally or replaying events during development.
When to use listen vs tunnel:Use listen when you already have a Hooklistener endpoint configured in your webhook provider. Use tunnel when you need a new public URL to configure.
Usage
hooklistener listen <ENDPOINT_SLUG> --target <URL>Find Your Endpoint Slug
- Create an endpoint in the Hooklistener dashboard (see setting up an endpoint) and paste its URL into your webhook provider.
- Copy the endpoint's slug from the dashboard. It looks like
stripe-checkout-x7kq. - Replace
YOUR_ENDPOINT_SLUGin the commands on this page with that slug, and set--targetto the URL your local server listens on.
Arguments and Options
| Argument / option | Description |
|---|---|
<ENDPOINT_SLUG> | (Required) Slug of the hosted endpoint to listen to |
--target <URL> | URL to forward each request to, such as http://localhost:3000 |
--help | Show help information |
How It Works
- Connect to endpoint: The CLI establishes a WebSocket connection to your Hooklistener endpoint.
- Receive webhooks: When a webhook arrives at your endpoint, it's streamed to the CLI in real-time.
- Forward locally: The CLI makes an HTTP request to your local server with the same method, headers, and body.
- Return response: Your local server's response is captured and logged.
Examples
Basic Usage
Forward webhooks from your endpoint to localhost:3000:
hooklistener listen YOUR_ENDPOINT_SLUG --target http://localhost:3000Target Your Webhook Route
Include the path of your webhook handler in the target URL:
hooklistener listen YOUR_ENDPOINT_SLUG --target http://localhost:3000/api/webhooksCustom Host
Forward to a different host (e.g., Docker container):
hooklistener listen YOUR_ENDPOINT_SLUG --target http://192.168.1.100:3000Checked September 2026
Hooklistener vs ngrok http vs hookdeck listen
All four commands forward webhooks to a local port. They differ in which URL the provider sees and what happens to a request after it arrives.
| Criteria | hooklistener tunnel | hooklistener listen | ngrok http | hookdeck listen |
|---|---|---|---|---|
| Command | hooklistener tunnel --port 3000 | hooklistener listen YOUR_ENDPOINT_SLUG --target http://localhost:3000 | ngrok http 3000 | hookdeck listen 3000 <source> |
| URL you give the provider | Random hook.events subdomain on Free; a static subdomain on paid plans | Your hosted endpoint URL, which doesn't change, on Free too | 1 static dev domain on Free | A permanent event URL per source |
| When your machine is offline | Requests aren't delivered while the tunnel is closed | The endpoint still captures requests; replay them later | Requests aren't delivered while the agent is stopped | Not documented |
| History and replay | Stored in the cloud: 1 day on Free, up to 90 days on Scale; replay to localhost | Stored in the cloud: 1 day on Free, up to 90 days on Scale; replay to localhost | Traffic Inspector, 24-hour retention on Free; replay needs opt-in Full Capture | CLI Events page and local retry (not in guest mode) |
| Free tier | 1 CLI tunnel at a time, 50 stored requests | 1 hosted endpoint, 50 stored requests | 20,000 HTTP requests/mo, 1 GB transfer; interstitial page on HTTP endpoints | Developer plan: 10,000 events/mo, 3-day retention |
| Pick it when | You want a public URL for a local port right now | You want a provider URL that never changes and no lost webhooks | You also need TCP/TLS tunnels or non-webhook traffic | You already route production events through Hookdeck |
Sources: ngrok pricing, ngrok Traffic Inspector, Hookdeck CLI docs, Hookdeck pricing, Hooklistener pricing.
Use Cases
Debug Production Webhooks
Your production webhook endpoint is already configured with services like Stripe or GitHub. Use listen to forward a copy of incoming webhooks to your local machine for debugging without changing the production configuration.
Replay Events
Hooklistener stores recent webhooks. You can replay them through the web dashboard and use listen to receive them locally again.
Team Development
Multiple developers can listen to the same endpoint simultaneously, each forwarding to their own local server.