Build and test a webhook handler on your own machine, with no public tunnel and no webhook endpoint in Kenso. kenso webhooks listen streams your workspace's events, prints each one as JSON and forwards it to your handler, signed the way Kenso signs its deliveries. kenso webhooks trigger sends a sample event through the running listener.
| Command | What it does |
|---|---|
webhooks listen --forward-to <url> | Streams events, prints one JSON line each, and POSTs each to your handler |
webhooks listen --print-secret | Prints the local signing secret and exits |
webhooks trigger <event-type> | Sends that type's sample through the running listener |
Quick start
In one terminal:
kenso webhooks listen --forward-to http://localhost:3000/hook
It prints its signing secret on stderr:
Ready. Forwarding events to http://localhost:3000/hook.
Signing secret: whsec_... (the same on every run; kept in ~/.kenso/webhooks/signing-secret).
Put that secret in your handler's config (for example KENSO_WEBHOOK_SECRET). In another terminal:
kenso webhooks trigger reply.received
The listener prints the event and your handler receives it. kenso webhook-event-types list lists every type with its sample body.
What your handler receives
Each forward is a POST with a JSON body shaped like a webhook delivery (no envelope, eventType at the top) and the headers a Kenso delivery carries. How full the body is depends on where the event came from:
- A trigger sends the type's full sample body, the same shape a webhook endpoint receives in production.
- A live event is sparse. The event log keeps only part of each delivery, so the body has
eventType,eventId,timestampandclientId, plus the ids, statuses andlinksat their delivery paths (contact.id,campaign.id,reply.classification, ...). Names, emails, reply text and the other fields are not there: read them with the API, or build that part of the handler against a trigger's sample.
The headers:
| Header | Value |
|---|---|
svix-id | The event's id. Dedupe on it |
svix-timestamp | Unix seconds of the send |
svix-signature | v1, and the base64 HMAC-SHA256 of {svix-id}.{svix-timestamp}.{body}, keyed by the secret |
content-type | application/json |
So the verification code you write for production works unchanged: the Svix libraries (svix for Node, Python, Go and others) and the check in the Webhooks section of the Kenso API docs accept these deliveries. Only the secret differs. The listener's secret is local: it is made on your machine the first time you run listen, stays the same on every run, and is never a real endpoint's secret. In production, use your endpoint's secret from kenso webhook-endpoints get-signing-secret --webhook-endpoint-id <webhookEndpointId>.
For scripts, take the secret without starting a listener:
export KENSO_WEBHOOK_SECRET=$(kenso webhooks listen --print-secret)
Output
stdout gets one JSON line per event, for jq or an agent:
{"eventId":"0b6f...","type":"reply.received","timestamp":"2026-11-15T10:00:00Z","source":"live","forward":{"url":"http://localhost:3000/hook","status":200,"ms":12},"data":{"eventType":"reply.received","...":"..."}}
sourceislivefor a real event andtriggerfor a sample.forwardis what your handler answered:status, orerror(ECONNREFUSEDwhen nothing listens there). It is absent without--forward-to.datais the body your handler received (or would receive, without--forward-to).
The ready line, the secret and the summary at Ctrl-C go to stderr.
Live events
listen reads the workspace's event log (GET /v1/event-occurrences), so it receives the types with mcp: true in kenso webhook-event-types list that your seat can see. It polls the log, so a real event arrives within about 30 s; a trigger arrives at once. --events reply.received,meeting.booked (or --events repeated) narrows the types.
The event log is not on for every workspace yet. Where it is off, listen says so in a warning and still forwards everything you trigger, so you can build the handler first.
Triggers
trigger takes the type's sample from GET /v1/webhook-event-types, gives it a new eventId (evt_test_...) and the current timestamp, and hands it to the listener for this workspace, which prints and forwards it like a live event. It sends nothing to Kenso's event log, to your webhook endpoints or to anyone else. It exits 1 with forward_failed when your handler did not answer 2xx, and with listener_not_running when no listener runs for the workspace.
To send a sample to a real, deployed endpoint instead, use kenso webhook-endpoints test --webhook-endpoint-id <webhookEndpointId> --event-type reply.received.
Stopping
Ctrl-C stops the listener. listen creates no webhook endpoint, no event subscription and no tunnel, so there is nothing to delete in Kenso. Its polls do keep the workspace's event log recording: the log stops on its own 7 days after the last poll. A poll that fails (a network error, a 5xx) prints a warning and is tried again a minute later; a bad key or a refused request ends the listener. It removes its local state file (the address trigger uses) on the way out.