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 loginrelay 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
| Flag | Description |
|---|---|
--forward-to <url> | Local URL that receives the events (required) |
--events <types> | Comma-separated types, e.g. invoice.*,user.created |
--print-body | Print each payload in the terminal |
--skip-verify | Accept 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