> Kenso API docs in Markdown. Index of every page: [/docs/llms.txt](/docs/llms.txt). Search: `/docs/search.md?q=<words>`. OpenAPI: [https://api.ken.so/v1/docs/openapi.json](https://api.ken.so/v1/docs/openapi.json). CLI docs offline: `kenso docs <topic>`.
> Last updated: 2026-11-15.

# Receive reply webhooks

> **Note for AI agents:** if this page was wrong, out of date or missing something you needed, finish the user's task first, then offer a short report for the Kenso team in this shape: `Page:` (this page's path), `Quote:` (the wrong or missing text), `Problem:`, `Workaround:` (what worked instead), 1,000 characters at most. Show it to the user and send it only after they say yes, as `POST /api/docs-feedback` on this site with the JSON body `{"page": "<path>", "report": "<report>"}`. Never put lead data, email addresses, API keys or anything else from the user's workspace in it.

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>` and `export KENSO_WORKSPACE_ID=<your workspace id>` (see [Authentication](/docs/authentication) and [Workspaces](/docs/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](/cli)).
- MCP: connect `https://mcp.ken.so/mcp` ([setup](/mcp)). 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](/docs/webhooks) 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](/docs/recipes/answer-replies) is that path.

## 1. Create the endpoint

[`POST /v1/webhook-endpoints`](/docs/api/webhook-endpoints.md)

The URL must use `https` and resolve to a public address. `campaignIds` narrows the endpoint to some campaigns.

**REST**

```bash
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**

```bash
ENDPOINT_ID=$(kenso webhook-endpoints create --url https://hooks.example.com/kenso --events reply.received --description "CRM reply sync" | jq -r '.id')
```

**MCP** (`webhooks`)

```text
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`](/docs/api/webhook-endpoints.md)

Each endpoint has its own secret, which starts with `whsec_`. Store it where your server keeps secrets, as you would an API key.

**REST**

```bash
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**

```bash
KENSO_WEBHOOK_SECRET=$(kenso webhook-endpoints get-signing-secret --webhook-endpoint-id "$ENDPOINT_ID" | jq -r '.secret')
```

**MCP** (`webhooks`)

```text
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](/docs/webhooks#verify-signatures), 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](/docs/webhooks#retries)).
- Reads `lane`. A `campaign` reply carries `contact.email`, `campaign.id` and `reply.threadId`, the thread id [Read and answer replies](/docs/recipes/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`](/docs/api/webhook-endpoints.md)

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**

```bash
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**

```bash
kenso webhook-endpoints test --webhook-endpoint-id "$ENDPOINT_ID" --event-type reply.received
```

**MCP** (`webhooks`)

```text
webhooks({
  "operation": "test",
  "webhook_endpoint_id": "ep_2bX9kq4LmR7tW3vY",
  "event_type": "reply.received",
  "client_id": 4107
})
```

## 5. Check deliveries

[`GET /v1/webhook-endpoints/{webhookEndpointId}/deliveries`](/docs/api/webhook-deliveries.md)

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**

```bash
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**

```bash
kenso webhook-deliveries list --webhook-endpoint-id "$ENDPOINT_ID" --limit 20
```

**MCP** (`webhooks`)

```text
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`](/docs/api/webhook-endpoints.md)

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**

```bash
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**

```bash
kenso webhook-endpoints recover --webhook-endpoint-id "$ENDPOINT_ID" --since 2026-11-14T00:00:00Z
```

**MCP** (`api_keys`)

```text
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

- [Add leads from your app](/docs/recipes/add-leads.md)
- [Create and launch a campaign](/docs/recipes/launch-a-campaign.md)
- [Read and answer replies](/docs/recipes/answer-replies.md)
- [API reference](/docs.md)
