Skip to content
HookNexus

Local forwarding

Local forwarding is a Pro feature. The CLI opens a WebSocket to HookNexus for your endpoint; each incoming webhook is replayed as an HTTP request to the URL you specify—ideal for local development without exposing a public URL.

How it works

  1. You run hooknexus forward with an endpoint ID and a --to target (normally http://localhost:...).
  2. The CLI maintains a live WebSocket subscription for that endpoint.
  3. When HookNexus receives a webhook, the CLI forwards the method, headers, query string, and body to your target.
  4. Responses are summarized in the terminal (status code, timing, truncated body).

Identification headers such as X-Forwarded-By, X-HookNexus-Request-Id, and X-HookNexus-Original-IP are added so your app can tell forwarded traffic apart.

Basic usage

Terminal window
hooknexus forward EP_ID --to http://localhost:3000/webhook

Replace EP_ID with your endpoint’s ID from the dashboard or hooknexus endpoints list.

Path mapping

By default, the request is sent to the exact URL you pass to --to. To append the path that followed /h/<endpoint-id> in the original request, use:

Terminal window
hooknexus forward EP_ID --to http://localhost:3000 --preserve-path

That way, extra path segments on the public webhook URL are preserved on your local server.

Multiple endpoints

Run one forward process per endpoint, each in its own terminal (or process manager), with its own --to URL. There is no single command that forwards several endpoints to different targets in one process.

For listening only (no HTTP forward), you can use hooknexus listen with multiple endpoint IDs or hooknexus listen --all.

Timeouts, headers, and non-local targets

OptionPurpose
--timeout <ms>HTTP timeout when calling your local server (default often 30s).
-H "Name: Value"Extra headers to add to the forwarded request (repeatable).
--allow-externalAllow --to to point outside localhost (use with care).
--insecureRelax TLS verification when needed for local dev (see CLI help).

Retry and resilience

  • WebSocket: If the connection to HookNexus drops, the CLI attempts to reconnect automatically.
  • HTTP forward: A failed forward (connection refused, timeout, etc.) is reported in the terminal; automatic retries for the same webhook are not guaranteed—fix your local server or trigger the webhook again from the provider.

Use cases

  • Local API development — Point Stripe, GitHub, or Shopify webhooks at HookNexus, then forward into localhost while you iterate.
  • Integration tests — Hit a stable public URL in CI or staging while your handler runs on your machine.
  • Debugging payloads — Combine forwarding with dashboard or hooknexus listen to compare raw vs forwarded behavior.