Commands
Webhooks
Receive SignatureAPI test webhooks at a handler on your machine with signatureapi listen, and send example events with signatureapi trigger.
Your webhook handler usually runs on localhost, where SignatureAPI cannot reach it. listen closes that gap: it registers a test-mode webhook endpoint for your machine and delivers events to your handler until you stop it. trigger sends an example event to that endpoint, so you can test the handler without signing an envelope.
Both commands work in test mode only. See Webhooks for how deliveries, retries, and signatures work.
listen
Start your application’s webhook handler, then run:
npx signatureapi listen --forward-to http://127.0.0.1:3000/webhooks
listen does four things:
- Registers a test-mode webhook endpoint for this machine, or updates the one it registered before.
- Saves the endpoint’s ID and signing secret into the env file, as
SIGNATUREAPI_WEBHOOK_IDandSIGNATUREAPI_WEBHOOK_SECRET. - Enables the endpoint and reports that it is listening.
- Delivers events to your handler until you stop it. Ctrl+C disables the endpoint.
The endpoint receives the account’s test-mode events, such as those from a test envelope you send, and every example trigger sends.
Choose a destination
Pass one of these options. Don’t combine them.
| Option | Description |
|---|---|
--forward-to <url> | Local URL of your webhook handler. A temporary public tunnel forwards each delivery to it. |
--public-url <url> | Public HTTPS URL you already expose. Deliveries go there with no tunnel. |
With --forward-to, the CLI forwards each delivery’s original body and signature headers, so your handler verifies it exactly as it would in production. Your handler has 30 seconds to respond. An HTTPS local target is verified against Node.js’s bundled certificate authorities and your operating system’s trust store, so a local certificate authority you trust system-wide works without extra setup.
The first --forward-to run downloads the tunnel client into a cache directory under ~/.cache/signatureapi (or under $XDG_CACHE_HOME) and verifies its checksum. On networks that block the tunnel, use --public-url with a tunnel you run yourself.
Options
| Option | Description |
|---|---|
--event <event-type> | Only subscribe to this event type. Repeatable. Default: every event type. |
--env-path <path> | Env file to write to, inside the current directory. Created when missing. Default: .env, or .env.local in Next.js projects. |
--webhook-id <webhook-id> | CLI webhook ID (cli_...) to use instead of the one saved in the env file. |
--webhook-id-var <name> | Env variable that holds the CLI webhook ID. Default: SIGNATUREAPI_WEBHOOK_ID. |
--secret-var <name> | Env variable that holds the webhook signing secret. Default: SIGNATUREAPI_WEBHOOK_SECRET. |
--replace | Overwrite a different signing secret already in the env file. |
The env file follows the same rules as for API keys. See How the CLI writes env files.
signatureapi listen --help lists every event type the installed version can subscribe to. The event types pages describe each one.
Examples:
# Forward every event to a local handler through a temporary tunnel
npx signatureapi listen --forward-to http://127.0.0.1:3000/webhooks
# Subscribe to two events only
npx signatureapi listen --forward-to http://127.0.0.1:3000/webhooks --event envelope.completed --event recipient.completed
# Deliver to a public HTTPS URL you already run
npx signatureapi listen --public-url https://my-tunnel.example/webhooks
Verify signatures
Verify every delivery in your handler, with the signing secret listen saved in SIGNATUREAPI_WEBHOOK_SECRET. Deliveries carry the webhook-id, webhook-timestamp, and webhook-signature headers. See Webhooks authentication for verification libraries.
Rerunning listen updates the same endpoint and keeps its signing secret, so your handler’s configuration stays valid between runs.
What the listener shows
With --forward-to, the listener prints one line per delivery: the event type, the delivery ID, your handler’s response status, and the time it took. With --json, it prints events you can parse:
listener_ready, once the secret is saved and the endpoint is enabled. It carrieswebhook_id,forward_to(the local target’s origin and path, without a query string; absent with--public-url), andevent_types(absent when every event type is subscribed).webhook_forwarded, for each delivery your handler answered.webhook_forward_failed, for each delivery your handler did not answer. Itsreasonishandler_unreachable,handler_timeout, ordelivery_closed.
Delivery events carry event_type, delivery_id, status_code (your handler’s response status, when it answered), and duration_ms. They never include the body or headers.
{"type":"progress","phase":"listen","code":"webhook_forwarded","event_type":"envelope.completed","delivery_id":"...","status_code":200,"duration_ms":42}
Stop the listener
Ctrl+C, terminating the process, or closing the terminal stops the listener and disables the endpoint. The final result says what happened:
| Code | Meaning |
|---|---|
listener_stopped | The listener stopped and disabled the endpoint. |
listener_superseded | Another listener took over this endpoint, so the CLI left it unchanged. |
listener_webhook_absent | The endpoint no longer exists. |
listener_cleanup_unavailable | The CLI could not confirm the endpoint was disabled. Check or disable it in the Dashboard’s Webhooks settings. |
Press Ctrl+C again during cleanup to exit after the tunnel closes; the CLI then says the endpoint may still be enabled. If the process crashes, the endpoint stays enabled until you run listen again, which repairs it.
Run more than one endpoint
Each endpoint is an ID and secret pair. To run a second one, for example for a worker, give it its own env file or its own variables:
# A second endpoint with its own env file
npx signatureapi listen --env-path .env.worker --forward-to http://127.0.0.1:8081/webhooks
# A second endpoint in the same env file, under other variable names
npx signatureapi listen --webhook-id-var WORKER_WEBHOOK_ID --secret-var WORKER_WEBHOOK_SECRET \
--forward-to http://127.0.0.1:8081/webhooks
Endpoints with different IDs can listen at the same time. When a second machine listens with the same ID, it takes the endpoint over, and the first listener reports listener_superseded when it stops.
trigger
With listen running in another terminal:
npx signatureapi trigger envelope.completed
Sends an example event to the endpoint listen registered. No envelope changes, and no other webhook endpoint receives it. The listener’s terminal shows the delivery and your handler’s response status.
| Argument or option | Description |
|---|---|
<event-type> | Event to send, such as envelope.completed. signatureapi trigger --help lists every event type. |
--env-path <path> | Env file that holds the webhook ID and signing secret. Default: .env, or .env.local in Next.js projects. |
--webhook-id <webhook-id> | CLI webhook ID (cli_...) to use instead of the one saved in the env file. |
--webhook-id-var <name> | Env variable that holds the CLI webhook ID. Default: SIGNATUREAPI_WEBHOOK_ID. |
--secret-var <name> | Env variable that holds the webhook signing secret. Default: SIGNATUREAPI_WEBHOOK_SECRET. |
# Send to a second endpoint's ID and secret
npx signatureapi trigger envelope.completed --webhook-id-var WORKER_WEBHOOK_ID --secret-var WORKER_WEBHOOK_SECRET
An example event tests your handler, not your whole flow. To check the flow end to end, send a test envelope and sign it.