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.
Before you start
- REST:
export KENSO_API_KEY=<your key>andexport KENSO_WORKSPACE_ID=<your workspace id>(see Authentication and Workspaces). The examples read ids withjq. kenso:npm i -g kenso,printf '%s' "$KENSO_API_KEY" | kenso auth login --with-key, thenkenso workspace use <your workspace id>. A command prints the response'sdatawithout 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 asclient_idand 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_repliedcovers campaign replies only, and subscribing to it next toreply.receiveddelivers every campaign reply twice. New integrations takereply.received.reply.classifiedis not open to every workspace yet:GET /v1/webhook-event-typeslists the types yours can use.POST /v1/event-subscriptionsis for AI agents connected over MCP: a subscription belongs to one member, lasts at most an hour, and does not offerreply.received.- Polling
GET /v1/threadssees 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.
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')ENDPOINT_ID=$(kenso webhook-endpoints create --url https://hooks.example.com/kenso --events reply.received --description "CRM reply sync" | jq -r '.id')
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.
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_WEBHOOK_SECRET=$(kenso webhook-endpoints get-signing-secret --webhook-endpoint-id "$ENDPOINT_ID" | jq -r '.secret')
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-signatureagainst the raw body, read before any JSON parsing, with the Node.js or Python function in Verify the signature, or Svix's open-sourcesvixlibrary. - Skips a delivery whose
svix-idit has handled: retries and resends repeat it. - Answers
2xxwithin 30 seconds and does the work from a queue. Anything else is retried for about 27 hours (retries). - Reads
lane. Acampaignreply carriescontact.email,campaign.idandreply.threadId, the thread id Read and answer replies takes. Anaccountsreply sendscontact,campaignandreplyasnulland carriesperson,accountandchannelinstead.
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.
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 webhook-endpoints test --webhook-endpoint-id "$ENDPOINT_ID" --event-type reply.received
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.
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 webhook-deliveries list --webhook-endpoint-id "$ENDPOINT_ID" --limit 20
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}.
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 webhook-endpoints recover --webhook-endpoint-id "$ENDPOINT_ID" --since 2026-11-14T00:00:00Z
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
integrationspermission. 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,
webhookswithoperation: "deliveries"lists inbound webhook deliveries, a different feature.