Local forwarding

Local forwarding is available on Free and Plus. The CLI keeps a WebSocket open for your endpoint; each incoming webhook is sent as an HTTP request to the URL you pass to --to—useful for local development without exposing a public port.

Target URL (--to)

--to must be a full URL: scheme, host, port (if not 80/443), and path—whatever route on your server should receive the forwarded POST (or other method). That path is defined by your framework and app, not by HookNexus.

If you only pass something like http://localhost:8788 with no path, the request hits / on your local server, which often returns 404. Replace PORT and PATH in the examples below with your real values.

Tip

The dashboard CLI forward helper copies a command template with http://localhost:PORT/PATH for the same reason: avoid assuming a specific webhook route (e.g. payment providers differ).

How it works

1. You run hooknexus forward with a --to target that includes the full local URL (see above).
2. The CLI subscribes to your endpoint over WebSocket.
3. When HookNexus receives a webhook, the CLI forwards method, headers, query, and body to your target.
4. Results (status, timing, truncated body) are summarized in the terminal.

The CLI may add identification headers (for example forwarding metadata); see hooknexus forward --help for the current set.

Basic usage

hooknexus forward --to http://localhost:PORT/PATH
hooknexus forward <endpoint-id> --to http://localhost:PORT/PATH

For example only (your path will differ): http://localhost:3000/webhook.

If you omit the endpoint id, selection behaves like hooknexus listen (auto-pick, prompt, or create).

Path mapping

By default the request is sent to the exact URL you pass to --to. To append path segments from the public HookNexus webhook URL onto your local origin, use --preserve-path (still start from a base like http://localhost:3000—understand how your server routes the combined path):

hooknexus forward --to http://localhost:3000 --preserve-path

Local vs non-local targets

By default only localhost, 127.0.0.1, and .local are allowed. To forward elsewhere:

hooknexus forward --to http://example.com/webhook --allow-external

Caution

--allow-external increases risk if you forward sensitive payloads to untrusted hosts. Use only when you understand the implications.

Multiple endpoints

Run one forward process per endpoint (separate terminal or process manager) with its own --to. For listen-only multiplexing, use hooknexus listen with multiple ids or --all.

Options

Common flags (see hooknexus forward --help for the full list):

Option	Purpose
--to <url>	Full target HTTP URL including path (required)
--preserve-path	Keep original path segments on the target
--allow-external	Allow non-localhost targets
--timeout <ms>	Timeout for the outbound HTTP forward
-H "Name: Value"	Extra headers on the forwarded request (repeatable)

Resilience

• WebSocket: The CLI attempts to reconnect if the connection to HookNexus drops.
• HTTP forward: Failures are reported in the terminal; retry behavior depends on your provider sending another webhook.

Related

• hooknexus/hooknexus-cli on GitHub
• Forward webhooks to localhost on hooknexus.com
• Command reference
• Realtime (WebSocket)
• Receive webhooks