Kenso
Kenso CLI

Webhooks: listen and trigger

Kenso CLI pages

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.

CommandWhat it does
webhooks listen --forward-to <url>Streams events, prints one JSON line each, and POSTs each to your handler
webhooks listen --print-secretPrints 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, timestamp and clientId, plus the ids, statuses and links at 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:

HeaderValue
svix-idThe event's id. Dedupe on it
svix-timestampUnix seconds of the send
svix-signaturev1, and the base64 HMAC-SHA256 of {svix-id}.{svix-timestamp}.{body}, keyed by the secret
content-typeapplication/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","...":"..."}}
  • source is live for a real event and trigger for a sample.
  • forward is what your handler answered: status, or error (ECONNREFUSED when nothing listens there). It is absent without --forward-to.
  • data is 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.