listen Command
The 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 <ENDPOINT_ID> --port <PORT> [OPTIONS]Options
| Option | Description |
|---|---|
--endpoint <ID> | (Required) The endpoint ID to listen to |
--port <PORT> | (Required) Local port to forward requests to |
--host <HOST> | Local host to forward to (default: localhost) |
--path-prefix <PATH> | Prepend a path prefix to all forwarded requests |
--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 endpoint to localhost:3000:
hooklistener listen --endpoint ep_abc123 --port 3000With Path Prefix
Add a path prefix to all forwarded requests:
hooklistener listen --endpoint ep_abc123 --port 3000 --path-prefix /api/webhooksA request to /github becomes /api/webhooks/github locally.
Custom Host
Forward to a different host (e.g., Docker container):
hooklistener listen --endpoint ep_abc123 --port 3000 --host 192.168.1.100Use 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.