CLI (evctl)

evctl is the EmailValidator command-line tool. Its primary use is forwarding webhook events to your local server during development — without a public URL or a tunnelling service.

Install

dotnet tool install -g evctl

Forward events to your local server

evctl listen --forward-to http://localhost:5000/your-hook --api-key ev_your_key

You can also set EV_API_KEY in your environment and omit the --api-key flag:

export EV_API_KEY=ev_your_key
evctl listen --forward-to http://localhost:5000/your-hook

How it works

evctl listen connects to the API's server-sent event stream, prints a signing secret, and forwards each event to your local endpoint — already signed — so your real signature-verification code runs against real payloads.

On startup evctl prints a session signing secret:

whsec_a1b2c3d4e5f6...
Ready! Forwarding to http://localhost:5000/your-hook

Copy the whsec_ value and use it as the secret in whichever verification snippet fits your stack (see Webhooks). The secret is ephemeral — a new one is generated each time evctl listen starts.

For each incoming event, evctl prints the event type, the HTTP status your handler returned, and the round-trip latency:

14:02:11  verify.completed  → 200 (12ms)

No ngrok, no reverse proxy, no changes to firewall rules. Your handler never needs to be reachable from the internet.

Fire a test delivery

Use POST /api/v1/webhooks/test to send a synthetic test event to any URL at any time. This is useful for confirming that your handler is reachable and that signature verification is wired up correctly before you run a real validation.

POST /api/v1/webhooks/test
X-Api-Key: ev_your_key
Content-Type: application/json

{ "callback_url": "https://yourapp.example.com/hooks/email" }

See Webhooks for the full delivery and signature reference.