Zean

Your server

Receive webhooks on your computer

The Zean CLI forwards the App’s events to your local server, signed like real calls.

Updated October 28, 2026

The webhook address must be public and use https. While you develop, the Zean CLI receives the App’s events and forwards them to your server, on your computer. Nothing to install: npx runs it, with Node.js 18 or later.

Run it

  1. Create a CLI key in App settings > Developers > Webhook > “CLI key”. See Keys and secrets.
  2. Start your server and its webhook route, for example on port 5000.
  3. Run the Zean CLI with the CLI key and that route’s address:
Terminal
npx zean-cli listen --key zk_cli_your_cli_key --forward http://localhost:5000/zean/webhook

The “Test events” card shows this command with your key, ready to copy. The key can also come from the environment:

Terminal
export ZEAN_CLI_KEY=zk_cli_your_cli_keynpx zean-cli listen --forward http://localhost:5000/zean/webhook
OptionTypeDescription
--keystringThe App’s CLI key, zk_cli_…. Without it: the ZEAN_CLI_KEY environment variable.
--forwardstringYour local server’s address that gets each event, such as http://localhost:5000/zean/webhook.

What it prints

  • At start: the App’s name, the address it forwards to and the Listen secret.
  • Then one line per call: the time, the event, whether it is a test, your server’s status code or the error, and how long it took in milliseconds.

The Listen secret

Each forwarded call carries the Zean-Event and Zean-Signature headers, signed exactly like a real call, but with the Listen secret. Your signature check works unchanged. See Verify a webhook signature.

  • In development: the Listen secret, printed by the Zean CLI.
  • In production: the webhook’s signing secret.
  • The Listen secret stays the same until the CLI key is regenerated.

What it forwards

  • Every real event of the App: it goes to the webhook address and to every running Zean CLI.
  • Test events sent from App settings > Developers > Webhook: they go only to the Zean CLI, with test set to true. See Receive events with a webhook.
  • Each call also shows in “Recent deliveries”, with “Zean CLI” as where it went.

Send a test event

  1. Keep the Zean CLI running: the “Test events” card counts it, and its button turns on.
  2. Pick the event, then “Send a test event”.
  3. The line shows in your terminal, and the call in “Recent deliveries” with your server’s reply.

Limits and stopping

  • Up to 5 Zean CLIs at once per App.
  • Ctrl+C stops it.
  • Regenerating the CLI key stops every running Zean CLI at once, with a message. Run it again with the new key, and update the Listen secret on your server.