Kenso

Receive reply webhooks

This path sends every reply to your server as a signed POST as it arrives. Delivery is at least once and in no set order, so your handler checks the signature, skips a delivery it has seen, and answers fast.

Ken-Version: 2026-11-02
Markdown

Before you start

  • REST: export KENSO_API_KEY=<your key> and export KENSO_WORKSPACE_ID=<your workspace id> (see Authentication and Workspaces). The examples read ids with jq.
  • kenso: npm i -g kenso, printf '%s' "$KENSO_API_KEY" | kenso auth login --with-key, then kenso workspace use <your workspace id>. A command prints the response's data without the envelope, and a list prints one JSON row per line (CLI guide).
  • MCP: connect https://mcp.ken.so/mcp (setup). Each tool takes the workspace id as client_id and returns the same body as the REST call.
  • Each step keeps the ids the next steps need in shell variables ($CAMPAIGN_ID). The MCP examples show the same ids as numbers.

The path

Create an endpoint for reply.received with POST /v1/webhook-endpoints, read its signing secret, verify each delivery, and prove the handler with a test send. The Webhooks guide has the verification code, the retry schedule and every payload.

  • lead_replied covers campaign replies only, and subscribing to it next to reply.received delivers every campaign reply twice. New integrations take reply.received.
  • reply.classified is not open to every workspace yet: GET /v1/webhook-event-types lists the types yours can use.
  • POST /v1/event-subscriptions is for AI agents connected over MCP: a subscription belongs to one member, lasts at most an hour, and does not offer reply.received.
  • Polling GET /v1/threads sees a reply only on your next poll. Read and answer replies is that path.

1. Create the endpoint

POST /v1/webhook-endpoints The URL must use https and resolve to a public address. campaignIds narrows the endpoint to some campaigns.

REST
ENDPOINT_ID=$(curl -sS -X POST "https://api.ken.so/v1/webhook-endpoints" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://hooks.example.com/kenso",
  "events": [
    "reply.received"
  ],
  "description": "CRM reply sync"
}' | jq -r '.data.id')
kenso
ENDPOINT_ID=$(kenso webhook-endpoints create --url https://hooks.example.com/kenso --events reply.received --description "CRM reply sync" | jq -r '.id')
MCP: webhooks
webhooks({
  "operation": "create",
  "url": "https://hooks.example.com/kenso",
  "events": [
    "reply.received"
  ],
  "description": "CRM reply sync",
  "client_id": 4107
})

Keeps data.id as $ENDPOINT_ID.

2. Read the signing secret

GET /v1/webhook-endpoints/{webhookEndpointId}/signing-secret Each endpoint has its own secret, which starts with whsec_. Store it where your server keeps secrets, as you would an API key.

REST
KENSO_WEBHOOK_SECRET=$(curl -sS -X GET "https://api.ken.so/v1/webhook-endpoints/$ENDPOINT_ID/signing-secret" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" | jq -r '.data.secret')
kenso
KENSO_WEBHOOK_SECRET=$(kenso webhook-endpoints get-signing-secret --webhook-endpoint-id "$ENDPOINT_ID" | jq -r '.secret')
MCP: webhooks
webhooks({
  "operation": "get-signing-secret",
  "webhook_endpoint_id": "ep_2bX9kq4LmR7tW3vY",
  "client_id": 4107
})

Keeps data.secret as $KENSO_WEBHOOK_SECRET.

3. Verify each delivery

Your handler does four things with every request:

  • Checks svix-signature against the raw body, read before any JSON parsing, with the Node.js or Python function in Verify the signature, or Svix's open-source svix library.
  • Skips a delivery whose svix-id it has handled: retries and resends repeat it.
  • Answers 2xx within 30 seconds and does the work from a queue. Anything else is retried for about 27 hours (retries).
  • Reads lane. A campaign reply carries contact.email, campaign.id and reply.threadId, the thread id Read and answer replies takes. An accounts reply sends contact, campaign and reply as null and carries person, account and channel instead.

4. Send a test

POST /v1/webhook-endpoints/{webhookEndpointId}/test Kenso signs the reply.received sample, with "test": true and made-up ids, sends it to this endpoint only and waits up to 5 seconds. data.attempt.status is success when your endpoint answered 2xx; no attempt means it had not answered yet.

REST
curl -sS -X POST "https://api.ken.so/v1/webhook-endpoints/$ENDPOINT_ID/test" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "eventType": "reply.received"
}'
kenso
kenso webhook-endpoints test --webhook-endpoint-id "$ENDPOINT_ID" --event-type reply.received
MCP: webhooks
webhooks({
  "operation": "test",
  "webhook_endpoint_id": "ep_2bX9kq4LmR7tW3vY",
  "event_type": "reply.received",
  "client_id": 4107
})

5. Check deliveries

GET /v1/webhook-endpoints/{webhookEndpointId}/deliveries Each attempt lists its status and the HTTP status your endpoint answered. Resend one with POST /v1/webhook-endpoints/{webhookEndpointId}/deliveries/{deliveryId}/resend, by its id or its messageId.

REST
curl -sS -X GET "https://api.ken.so/v1/webhook-endpoints/$ENDPOINT_ID/deliveries?limit=20" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"
kenso
kenso webhook-deliveries list --webhook-endpoint-id "$ENDPOINT_ID" --limit 20
MCP: webhooks
webhooks({
  "operation": "webhook-deliveries-list",
  "webhook_endpoint_id": "ep_2bX9kq4LmR7tW3vY",
  "limit": 20,
  "client_id": 4107
})

6. Recover after an outage

POST /v1/webhook-endpoints/{webhookEndpointId}/recover Once your endpoint is back, resend every delivery that failed since since, a time in the last 14 days: replace the example's date. date -u -d '1 day ago' +%FT%TZ prints yesterday on Linux, date -u -v-1d +%FT%TZ on macOS. It answers 202 and resends in the background. In the MCP, recover is on the api_keys tool. If the endpoint failed for 5 days straight, Kenso disabled it: turn it back on first with PATCH /v1/webhook-endpoints/{webhookEndpointId} and {"isDisabled": false}.

REST
curl -sS -X POST "https://api.ken.so/v1/webhook-endpoints/$ENDPOINT_ID/recover" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "since": "2026-11-14T00:00:00Z"
}'
kenso
kenso webhook-endpoints recover --webhook-endpoint-id "$ENDPOINT_ID" --since 2026-11-14T00:00:00Z
MCP: api_keys
api_keys({
  "operation": "webhook-endpoints-recover",
  "webhook_endpoint_id": "ep_2bX9kq4LmR7tW3vY",
  "since": "2026-11-14T00:00:00Z",
  "client_id": 4107
})

Good to know

  • Every webhook call needs the integrations permission. A workspace holds at most 25 endpoints, disabled ones included.
  • There is no call to rotate a secret: add a new endpoint, switch your handler to its secret, then delete the old one.
  • A test send ignores the endpoint's filters, so it does not prove real events match them.
  • Resends share a workspace limit of 30 a minute and 1,000 a day, and one recover counts as 10.
  • In the MCP, webhooks with operation: "deliveries" lists inbound webhook deliveries, a different feature.

More recipes and guides