Skip to content
RelayDocumentation

GuidesGuides

Test locally with the CLI

Forward live events to localhost, trigger sample events and replay past deliveries.

The Relay CLI opens a secure tunnel from Relay to your machine. No ngrok, no public URL, no firewall changes.

Install and log in

brew install relay-cli
relay login

relay login opens your browser and stores a test-mode key in ~/.config/relay.

Forward events

relay listen --forward-to http://localhost:3000/api/webhooks
> Ready! Forwarding to http://localhost:3000/api/webhooks
> Signing secret for this session: whsec_test_8f2a91c3
2026-10-14 09:31:12  invoice.paid      evt_9fK2mLq81  → 200 (38 ms)
2026-10-14 09:31:40  user.created      evt_9fK2pQx02  → 500 (12 ms)

The session prints its own signing secret. Put it in .env.local while you test, because it's different from the secret of your production endpoint.

Options

FlagDescription
--forward-to <url>Local URL that receives the events (required)
--events <types>Comma-separated types, e.g. invoice.*,user.created
--print-bodyPrint each payload in the terminal
--skip-verifyAccept self-signed certificates on https://localhost

Trigger sample events

relay events trigger invoice.paid
relay events trigger user.created --data '{"email": "maya@example.com"}'

Replay a delivery

Fixing a bug that broke a real event? Send that exact event to your local server:

relay events replay evt_9fK2pQx02 --forward-to http://localhost:3000/api/webhooks