outworx forward — webhooks to localhost

Pick your runtime

The CLI ships inside both the npm and PyPI packages. No standalone install needed.

# No install needed — npx pulls the latest
npx outworx forward 3000

# Or install globally
npm install -g @outworx/hooks
outworx forward 3000

pip install outworx-hooks
outworx forward 3000

Set your API key

Grab the project API key from your dashboard. The CLI reads it from OUTWORX_API_KEY or the --api-key flag.

# Set once in your shell or .env
export OUTWORX_API_KEY=ow_live_...

# Run
npx outworx forward 3000

Run it

The CLI prints a unique public URL. Anything POSTed there is replayed to your local server, and the response your handler returns is relayed back to the provider — synchronously, like a normal request.

  outworx forward  →  http://localhost:3000
  Public URL:  https://hooks.outworx.io/t/8b3a9f1c2d4e5067
  Expires:     11/7/2026, 4:18:42 PM
  Press Ctrl+C to stop.

  16:18:51  POST /webhooks/stripe  200  42ms
  16:18:52  POST /webhooks/stripe  200  31ms

Now point a real provider at the public URL:

# Tell Stripe to deliver to the printed Public URL
stripe webhooks create \
  --url https://hooks.outworx.io/t/8b3a9f1c2d4e5067 \
  --enabled-events charge.succeeded,invoice.paid

# Then trigger an event
stripe trigger charge.succeeded

Things to know

• Sessions expire after 24 hours. Restart the CLI to get a fresh URL — the old one returns 410 Gone.
• Pro plan or higher. Each held tunnel call burns server function-seconds, so the feature is gated. Free-plan keys get 402 Payment Required.
• 25-second hold window. If your local handler doesn't respond in 25s, the tunnel returns 504 to the provider. Most webhook providers also enforce ~10–30s timeouts.
• Detect tunneled traffic. Outworx adds X-Outworx-Tunnel: <slug> to every relayed response — handy if you want your handler to behave differently for replays.
• Shorthand inputs. outworx forward 3000 is equivalent to outworx forward http://localhost:3000.