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

# Webhook endpoints

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

Endpoints Kenso posts events to: register them, read their signing secret, send a test and resend failed deliveries.

Integrations. 9 endpoints under `https://api.ken.so`. Every request sends `Authorization: Bearer <your API key>` and `Ken-Version: 2026-11-02`: see [Authentication](/docs/authentication.md), [Workspaces](/docs/workspaces.md) and [Errors](/docs/errors.md). OpenAPI for this resource only: [/docs/api/webhook-endpoints/openapi.json](/docs/api/webhook-endpoints/openapi.json).

Guide: [Webhooks](/docs/webhooks.md) - Receive events, verify their signatures, and handle retries and duplicates.

- `GET /v1/webhook-endpoints` - List webhook endpoints (`webhook-endpoints.list`): [/docs/api/webhook-endpoints/list.md](/docs/api/webhook-endpoints/list.md)
- `POST /v1/webhook-endpoints` - Create a webhook endpoint (`webhook-endpoints.create`): [/docs/api/webhook-endpoints/create.md](/docs/api/webhook-endpoints/create.md)
- `GET /v1/webhook-endpoints/{webhookEndpointId}` - Get a webhook endpoint (`webhook-endpoints.get`): [/docs/api/webhook-endpoints/get.md](/docs/api/webhook-endpoints/get.md)
- `PATCH /v1/webhook-endpoints/{webhookEndpointId}` - Update a webhook endpoint (`webhook-endpoints.update`): [/docs/api/webhook-endpoints/update.md](/docs/api/webhook-endpoints/update.md)
- `DELETE /v1/webhook-endpoints/{webhookEndpointId}` - Delete a webhook endpoint (`webhook-endpoints.delete`): [/docs/api/webhook-endpoints/delete.md](/docs/api/webhook-endpoints/delete.md)
- `POST /v1/webhook-endpoints/{webhookEndpointId}/recover` - Resend an endpoint's failed deliveries (`webhook-endpoints.recover`): [/docs/api/webhook-endpoints/recover.md](/docs/api/webhook-endpoints/recover.md)
- `POST /v1/webhook-endpoints/{webhookEndpointId}/test` - Send a test event (`webhook-endpoints.test`): [/docs/api/webhook-endpoints/test.md](/docs/api/webhook-endpoints/test.md)
- `GET /v1/webhook-endpoints/{webhookEndpointId}/signing-secret` - Get an endpoint's signing secret (`webhook-endpoints.get-signing-secret`): [/docs/api/webhook-endpoints/get-signing-secret.md](/docs/api/webhook-endpoints/get-signing-secret.md)
- `POST /v1/webhook-endpoints/{webhookEndpointId}/signing-secret/rotate` - Rotate an endpoint's signing secret (`webhook-endpoints.rotate-signing-secret`): [/docs/api/webhook-endpoints/rotate-signing-secret.md](/docs/api/webhook-endpoints/rotate-signing-secret.md)

## List webhook endpoints

`GET /v1/webhook-endpoints` - operationId `webhook-endpoints.list`

| Permission | Rate limit |
| --- | --- |
| The `integrations` permission | 12,000 requests a minute per API key |

Returns the workspace's webhook endpoints. Each endpoint's `health`, `lastDelivery` and
`failedAttempts` come from its latest 10 delivery attempts.

Requires the `integrations` permission.

[Try it on developer.ken.so](https://developer.ken.so/reference/#kenso-api/tag/webhook-endpoints/GET/v1/webhook-endpoints)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `limit` | query | integer (int32) | no | Endpoints per page, from 1 to 200. Default 50. |
| `cursor` | query | string | no | The `pagination.nextCursor` of the previous page. Omit it for the first page. |
| `Ken-Version` | header | string, one of: 2026-11-02, 1.1 | no | The API version, a date in `YYYY-MM-DD` form. `1.1` is another name for the first dated version. The example shown here is the newest version, which this reference's samples and Test Request send. Leave it out to use your API key's pinned version. Keys created in the Kenso app are pinned to the newest version; keys minted by the CLI login are not. A key with no pinned version and no header gets the legacy shape where the path has one, and `404` where the path exists only in this version. A value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions. |
| `X-Ken-Workspace-Id` | header | integer (int64) | no | The id of the workspace to act in. Leave it out when your API key reaches only one workspace. When the key reaches more than one, a request without this header answers `400 workspace_required`. A workspace you are not a member of answers `404 not_found`. |

### Response 200

`data` is a list of `WebhookEndpoint`. Each item has these fields. The response also carries `pagination`.

| Field | Type | Description |
| --- | --- | --- |
| `id` | string | The endpoint id, a string that starts with `ep_`. |
| `url` | string | The https URL Kenso sends events to. |
| `events` | array of string | The event types the endpoint receives. Empty means every event type. A `2026-12` endpoint lists the dotted names, such as `email.sent` for `email_sent`. |
| `description` | string | Your own note about the endpoint. Null when none was set. |
| `isDisabled` | boolean | True when delivery to this endpoint is paused. |
| `createdAt` | string (date-time) | When the endpoint was created, in UTC. |
| `app` | string | The app the endpoint belongs to: `zapier`, `make` or `n8n`. Null otherwise. |
| `health` | string | The endpoint's health: `active`, `failing` (the newest attempt failed) or `disabled`. Omitted, together with `lastDelivery` and `failedAttempts`, when Kenso could not read the delivery log. |
| `lastDelivery` | WebhookLastDelivery | The newest delivery attempt. Omitted when there is none yet. |
| `failedAttempts` | integer (int32) | Failed attempts since the newest success, among the latest 10 attempts. 0 unless the endpoint is failing. |
| `campaignIds` | array of integer (int64) | The campaign filter: the endpoint receives only events of these campaigns. Empty means every event. A filtered endpoint never receives an event that has no campaign. |
| `classifications` | array of string | The classification filter, as snake_case reply classifications such as `interested`. The endpoint receives only events whose reply has one of them. Empty means every event. A filtered endpoint never receives an event without a reply classification. With `campaignIds` also set, an event must match both. |
| `isBatched` | boolean | True when the high-volume event types arrive as `<type>.batch` deliveries of up to 100 events (`{eventType, eventId, timestamp, clientId, count, events}`), never one by one. |
| `schemaVersion` | string | The payload schema the endpoint receives: `2026-11`, or `2026-12`, which sends `workspaceId` for `clientId`, leaves out null values, writes enum values in snake_case and names every event type dotted. |

### Request

```bash
curl -X GET "https://api.ken.so/v1/webhook-endpoints?limit=50" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"
```

### Example response

```json
{
  "success": true,
  "data": [
    {
      "id": "ep_2bKq8yZ0aB3cD4eF5gH6iJ7kL8m",
      "url": "https://hooks.example.com/kenso/replies",
      "events": [
        "reply.classified"
      ],
      "description": "Interested replies into our CRM",
      "isDisabled": false,
      "createdAt": "2026-09-23T15:02:11Z",
      "health": "active",
      "lastDelivery": {
        "occurredAt": "2026-10-13T16:22:41Z",
        "status": "success",
        "responseStatusCode": 200,
        "eventType": "reply.classified"
      },
      "failedAttempts": 0,
      "campaignIds": [
        4821
      ],
      "classifications": [
        "interested"
      ],
      "isBatched": false,
      "schemaVersion": "2026-11"
    }
  ],
  "pagination": {
    "nextCursor": "eyJpZCI6ODE1fQ",
    "hasMore": true,
    "total": 1,
    "totalCount": 1,
    "isTotalCapped": true
  }
}
```

## Create a webhook endpoint

`POST /v1/webhook-endpoints` - operationId `webhook-endpoints.create`

| Permission | Rate limit |
| --- | --- |
| The `integrations` permission | 4,800 requests a minute per API key |

Registers a URL that receives the event types you list. Kenso starts sending matching events to it right away.

`url` is required. It must use https and resolve to a public address. `events` is required and lists at
least one event type from `GET /v1/webhook-event-types`. A type's alias from that list, such as
`email.sent` for `email_sent`, names the same type, and a type listed twice is subscribed once, so the
endpoint gets each event once. `app` tags the endpoint as `zapier`,
`make` or `n8n`. When you omit `app`, Kenso takes it from the URL host.

`campaignIds` and `classifications` filter deliveries. When both are set, an event must match both. A
filter holds at most 10 campaigns, 10 classifications, or campaigns times classifications up to 10.
`isBatched` sends the high-volume event types in batches, and needs an `events` list.
`schemaVersion` picks the payload schema: `2026-11`, the default, or `2026-12`, which is rolling out
and needs an `events` list and no batch delivery. An enabled endpoint without an `events` list receives
every event type, the `2026-12` deliveries included, so while one is enabled in the workspace a
`2026-12` endpoint is refused.

A workspace holds at most 25 endpoints.

Errors:

- `400 validation_failed`: `url` is missing, not https or not public, an event type is unknown to
the workspace, `app` or a classification is unknown, the filter is too large, batch delivery is not
available to the workspace yet, or `schemaVersion` is unknown or not available to the workspace yet. Also
for `schemaVersion` `2026-12` while another enabled endpoint has no `events` list: give that
endpoint an `events` list first.
- `404 not_found`: a campaign in `campaignIds` is not in the workspace.
- `409 conflict`: the workspace already has 25 endpoints. Delete one first.

Requires the `integrations` permission.

[Try it on developer.ken.so](https://developer.ken.so/reference/#kenso-api/tag/webhook-endpoints/POST/v1/webhook-endpoints)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `Ken-Version` | header | string, one of: 2026-11-02, 1.1 | no | The API version, a date in `YYYY-MM-DD` form. `1.1` is another name for the first dated version. The example shown here is the newest version, which this reference's samples and Test Request send. Leave it out to use your API key's pinned version. Keys created in the Kenso app are pinned to the newest version; keys minted by the CLI login are not. A key with no pinned version and no header gets the legacy shape where the path has one, and `404` where the path exists only in this version. A value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions. |
| `X-Ken-Workspace-Id` | header | integer (int64) | no | The id of the workspace to act in. Leave it out when your API key reaches only one workspace. When the key reaches more than one, a request without this header answers `400 workspace_required`. A workspace you are not a member of answers `404 not_found`. |

### Request body

`application/json`, optional.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | string | yes | Required. The https URL that receives events. It must resolve to a public address, and has at most 2,048 characters. |
| `events` | array of string | yes | Required. The event types the endpoint receives, at least one, from `GET /v1/webhook-event-types`. A type's alias names the same type. |
| `description` | string | no | Your own note about the endpoint, at most 500 characters. |
| `app` | string | no | The app the endpoint belongs to: `zapier`, `make` or `n8n`. Omitted: Kenso takes it from the URL host when the host belongs to one of them. |
| `campaignIds` | array of integer (int64) | no | Deliver only events of these campaigns of the workspace. Omitted or empty: every campaign. |
| `classifications` | array of string | no | Deliver only events whose reply has one of these classifications, in snake_case, such as `interested`. Omitted or empty: every classification. |
| `isBatched` | boolean | no | True to receive the high-volume event types in batches. Needs an `events` list. Default false. |
| `schemaVersion` | string | no | The payload schema: `2026-11` (the default) or `2026-12`, which is rolling out and offered only to the workspaces that have it. `2026-12` needs an `events` list and no batch delivery. |

### Response 201

`data` is a `WebhookEndpoint`.

| Field | Type | Description |
| --- | --- | --- |
| `id` | string | The endpoint id, a string that starts with `ep_`. |
| `url` | string | The https URL Kenso sends events to. |
| `events` | array of string | The event types the endpoint receives. Empty means every event type. A `2026-12` endpoint lists the dotted names, such as `email.sent` for `email_sent`. |
| `description` | string | Your own note about the endpoint. Null when none was set. |
| `isDisabled` | boolean | True when delivery to this endpoint is paused. |
| `createdAt` | string (date-time) | When the endpoint was created, in UTC. |
| `app` | string | The app the endpoint belongs to: `zapier`, `make` or `n8n`. Null otherwise. |
| `health` | string | The endpoint's health: `active`, `failing` (the newest attempt failed) or `disabled`. Omitted, together with `lastDelivery` and `failedAttempts`, when Kenso could not read the delivery log. |
| `lastDelivery` | WebhookLastDelivery | The newest delivery attempt. Omitted when there is none yet. |
| `failedAttempts` | integer (int32) | Failed attempts since the newest success, among the latest 10 attempts. 0 unless the endpoint is failing. |
| `campaignIds` | array of integer (int64) | The campaign filter: the endpoint receives only events of these campaigns. Empty means every event. A filtered endpoint never receives an event that has no campaign. |
| `classifications` | array of string | The classification filter, as snake_case reply classifications such as `interested`. The endpoint receives only events whose reply has one of them. Empty means every event. A filtered endpoint never receives an event without a reply classification. With `campaignIds` also set, an event must match both. |
| `isBatched` | boolean | True when the high-volume event types arrive as `<type>.batch` deliveries of up to 100 events (`{eventType, eventId, timestamp, clientId, count, events}`), never one by one. |
| `schemaVersion` | string | The payload schema the endpoint receives: `2026-11`, or `2026-12`, which sends `workspaceId` for `clientId`, leaves out null values, writes enum values in snake_case and names every event type dotted. |

### Request

```bash
curl -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/replies",
  "events": [
    "reply.classified"
  ],
  "description": "Interested replies into our CRM",
  "campaignIds": [
    4821
  ],
  "classifications": [
    "interested"
  ],
  "isBatched": false
}'
```

### Example response

```json
{
  "success": true,
  "data": {
    "id": "ep_2bKq8yZ0aB3cD4eF5gH6iJ7kL8m",
    "url": "https://hooks.example.com/kenso/replies",
    "events": [
      "reply.classified"
    ],
    "description": "Interested replies into our CRM",
    "isDisabled": false,
    "createdAt": "2026-09-23T15:02:11Z",
    "health": "active",
    "lastDelivery": {
      "occurredAt": "2026-10-13T16:22:41Z",
      "status": "success",
      "responseStatusCode": 200,
      "eventType": "reply.classified"
    },
    "failedAttempts": 0,
    "campaignIds": [
      4821
    ],
    "classifications": [
      "interested"
    ],
    "isBatched": false,
    "schemaVersion": "2026-11"
  }
}
```

## Get a webhook endpoint

`GET /v1/webhook-endpoints/{webhookEndpointId}` - operationId `webhook-endpoints.get`

| Permission | Rate limit |
| --- | --- |
| The `integrations` permission | 12,000 requests a minute per API key |

Returns one webhook endpoint. Its `health`, `lastDelivery` and `failedAttempts` come from its
latest 10 delivery attempts.

Errors:

- `404 not_found`: the workspace has no endpoint with this id.

Requires the `integrations` permission.

[Try it on developer.ken.so](https://developer.ken.so/reference/#kenso-api/tag/webhook-endpoints/GET/v1/webhook-endpoints/%7BwebhookEndpointId%7D)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `webhookEndpointId` | path | string | yes | The webhook endpoint's id, which starts with `ep_`. |
| `Ken-Version` | header | string, one of: 2026-11-02, 1.1 | no | The API version, a date in `YYYY-MM-DD` form. `1.1` is another name for the first dated version. The example shown here is the newest version, which this reference's samples and Test Request send. Leave it out to use your API key's pinned version. Keys created in the Kenso app are pinned to the newest version; keys minted by the CLI login are not. A key with no pinned version and no header gets the legacy shape where the path has one, and `404` where the path exists only in this version. A value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions. |
| `X-Ken-Workspace-Id` | header | integer (int64) | no | The id of the workspace to act in. Leave it out when your API key reaches only one workspace. When the key reaches more than one, a request without this header answers `400 workspace_required`. A workspace you are not a member of answers `404 not_found`. |

### Response 200

`data` is a `WebhookEndpoint`.

| Field | Type | Description |
| --- | --- | --- |
| `id` | string | The endpoint id, a string that starts with `ep_`. |
| `url` | string | The https URL Kenso sends events to. |
| `events` | array of string | The event types the endpoint receives. Empty means every event type. A `2026-12` endpoint lists the dotted names, such as `email.sent` for `email_sent`. |
| `description` | string | Your own note about the endpoint. Null when none was set. |
| `isDisabled` | boolean | True when delivery to this endpoint is paused. |
| `createdAt` | string (date-time) | When the endpoint was created, in UTC. |
| `app` | string | The app the endpoint belongs to: `zapier`, `make` or `n8n`. Null otherwise. |
| `health` | string | The endpoint's health: `active`, `failing` (the newest attempt failed) or `disabled`. Omitted, together with `lastDelivery` and `failedAttempts`, when Kenso could not read the delivery log. |
| `lastDelivery` | WebhookLastDelivery | The newest delivery attempt. Omitted when there is none yet. |
| `failedAttempts` | integer (int32) | Failed attempts since the newest success, among the latest 10 attempts. 0 unless the endpoint is failing. |
| `campaignIds` | array of integer (int64) | The campaign filter: the endpoint receives only events of these campaigns. Empty means every event. A filtered endpoint never receives an event that has no campaign. |
| `classifications` | array of string | The classification filter, as snake_case reply classifications such as `interested`. The endpoint receives only events whose reply has one of them. Empty means every event. A filtered endpoint never receives an event without a reply classification. With `campaignIds` also set, an event must match both. |
| `isBatched` | boolean | True when the high-volume event types arrive as `<type>.batch` deliveries of up to 100 events (`{eventType, eventId, timestamp, clientId, count, events}`), never one by one. |
| `schemaVersion` | string | The payload schema the endpoint receives: `2026-11`, or `2026-12`, which sends `workspaceId` for `clientId`, leaves out null values, writes enum values in snake_case and names every event type dotted. |

### Request

```bash
curl -X GET "https://api.ken.so/v1/webhook-endpoints/ep_2bX9kq4LmR7tW3vY" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"
```

### Example response

```json
{
  "success": true,
  "data": {
    "id": "ep_2bKq8yZ0aB3cD4eF5gH6iJ7kL8m",
    "url": "https://hooks.example.com/kenso/replies",
    "events": [
      "reply.classified"
    ],
    "description": "Interested replies into our CRM",
    "isDisabled": false,
    "createdAt": "2026-09-23T15:02:11Z",
    "health": "active",
    "lastDelivery": {
      "occurredAt": "2026-10-13T16:22:41Z",
      "status": "success",
      "responseStatusCode": 200,
      "eventType": "reply.classified"
    },
    "failedAttempts": 0,
    "campaignIds": [
      4821
    ],
    "classifications": [
      "interested"
    ],
    "isBatched": false,
    "schemaVersion": "2026-11"
  }
}
```

## Update a webhook endpoint

`PATCH /v1/webhook-endpoints/{webhookEndpointId}` - operationId `webhook-endpoints.update`

| Permission | Rate limit |
| --- | --- |
| The `integrations` permission | 4,800 requests a minute per API key |

Changes the fields you send. Omitted fields keep their values.

`isDisabled` pauses or resumes delivery. `app` sets the app tag, and an empty string clears it.
`campaignIds` and `classifications` each replace that filter, and an empty list clears it. The filter
you omit keeps its value. `isBatched` turns batch delivery on or off, and needs the endpoint to have an
`events` list. `schemaVersion` switches the payload schema. The rules for `url`, `events`, the
filters and `schemaVersion` are the same as on create. An enabled `2026-12` endpoint and an enabled
endpoint without an `events` list never stay enabled together in a workspace, so this refuses both a switch
to `2026-12` while another enabled endpoint has no `events` list, and re-enabling (`isDisabled`
false) an endpoint without an `events` list, or a `2026-12` one, that would pair them.

Errors:

- `400 validation_failed`: a field breaks the rules above.
- `404 not_found`: the workspace has no endpoint with this id, or a campaign in `campaignIds` is not
in the workspace.

Requires the `integrations` permission.

[Try it on developer.ken.so](https://developer.ken.so/reference/#kenso-api/tag/webhook-endpoints/PATCH/v1/webhook-endpoints/%7BwebhookEndpointId%7D)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `webhookEndpointId` | path | string | yes | The webhook endpoint's id, which starts with `ep_`. |
| `Ken-Version` | header | string, one of: 2026-11-02, 1.1 | no | The API version, a date in `YYYY-MM-DD` form. `1.1` is another name for the first dated version. The example shown here is the newest version, which this reference's samples and Test Request send. Leave it out to use your API key's pinned version. Keys created in the Kenso app are pinned to the newest version; keys minted by the CLI login are not. A key with no pinned version and no header gets the legacy shape where the path has one, and `404` where the path exists only in this version. A value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions. |
| `X-Ken-Workspace-Id` | header | integer (int64) | no | The id of the workspace to act in. Leave it out when your API key reaches only one workspace. When the key reaches more than one, a request without this header answers `400 workspace_required`. A workspace you are not a member of answers `404 not_found`. |

### Request body

`application/json`, optional.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | string | no | A new https URL. It must resolve to a public address. |
| `events` | array of string | no | A new list of event types or their aliases, at least one. It replaces the current list. |
| `description` | string | no | A new note about the endpoint, at most 500 characters. |
| `isDisabled` | boolean | no | True pauses delivery to the endpoint. False resumes it. |
| `app` | string | no | The app the endpoint belongs to: `zapier`, `make` or `n8n`. An empty string clears it. |
| `campaignIds` | array of integer (int64) | no | A new campaign filter that replaces the current one. Empty means every campaign. |
| `classifications` | array of string | no | A new classification filter, in snake_case, that replaces the current one. Empty means every classification. |
| `isBatched` | boolean | no | True to receive the high-volume event types in batches, false to receive them one by one. |
| `schemaVersion` | string | no | A new payload schema, `2026-11` or `2026-12`, with the same rules as on create. |

### Response 200

`data` is a `WebhookEndpoint`.

| Field | Type | Description |
| --- | --- | --- |
| `id` | string | The endpoint id, a string that starts with `ep_`. |
| `url` | string | The https URL Kenso sends events to. |
| `events` | array of string | The event types the endpoint receives. Empty means every event type. A `2026-12` endpoint lists the dotted names, such as `email.sent` for `email_sent`. |
| `description` | string | Your own note about the endpoint. Null when none was set. |
| `isDisabled` | boolean | True when delivery to this endpoint is paused. |
| `createdAt` | string (date-time) | When the endpoint was created, in UTC. |
| `app` | string | The app the endpoint belongs to: `zapier`, `make` or `n8n`. Null otherwise. |
| `health` | string | The endpoint's health: `active`, `failing` (the newest attempt failed) or `disabled`. Omitted, together with `lastDelivery` and `failedAttempts`, when Kenso could not read the delivery log. |
| `lastDelivery` | WebhookLastDelivery | The newest delivery attempt. Omitted when there is none yet. |
| `failedAttempts` | integer (int32) | Failed attempts since the newest success, among the latest 10 attempts. 0 unless the endpoint is failing. |
| `campaignIds` | array of integer (int64) | The campaign filter: the endpoint receives only events of these campaigns. Empty means every event. A filtered endpoint never receives an event that has no campaign. |
| `classifications` | array of string | The classification filter, as snake_case reply classifications such as `interested`. The endpoint receives only events whose reply has one of them. Empty means every event. A filtered endpoint never receives an event without a reply classification. With `campaignIds` also set, an event must match both. |
| `isBatched` | boolean | True when the high-volume event types arrive as `<type>.batch` deliveries of up to 100 events (`{eventType, eventId, timestamp, clientId, count, events}`), never one by one. |
| `schemaVersion` | string | The payload schema the endpoint receives: `2026-11`, or `2026-12`, which sends `workspaceId` for `clientId`, leaves out null values, writes enum values in snake_case and names every event type dotted. |

### Request

```bash
curl -X PATCH "https://api.ken.so/v1/webhook-endpoints/ep_2bX9kq4LmR7tW3vY" \
  -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/replies",
  "events": [
    "reply.classified"
  ],
  "description": "Interested and referral replies into our CRM",
  "isDisabled": false,
  "campaignIds": [
    4821
  ],
  "classifications": [
    "interested",
    "referral"
  ],
  "isBatched": false
}'
```

### Example response

```json
{
  "success": true,
  "data": {
    "id": "ep_2bKq8yZ0aB3cD4eF5gH6iJ7kL8m",
    "url": "https://hooks.example.com/kenso/replies",
    "events": [
      "reply.classified"
    ],
    "description": "Interested replies into our CRM",
    "isDisabled": false,
    "createdAt": "2026-09-23T15:02:11Z",
    "health": "active",
    "lastDelivery": {
      "occurredAt": "2026-10-13T16:22:41Z",
      "status": "success",
      "responseStatusCode": 200,
      "eventType": "reply.classified"
    },
    "failedAttempts": 0,
    "campaignIds": [
      4821
    ],
    "classifications": [
      "interested"
    ],
    "isBatched": false,
    "schemaVersion": "2026-11"
  }
}
```

## Delete a webhook endpoint

`DELETE /v1/webhook-endpoints/{webhookEndpointId}` - operationId `webhook-endpoints.delete`

| Permission | Rate limit |
| --- | --- |
| The `integrations` permission | 4,800 requests a minute per API key |

Deletes the endpoint. Kenso stops sending events to its URL.

Errors:

- `404 not_found`: the workspace has no endpoint with this id.

Requires the `integrations` permission.

[Try it on developer.ken.so](https://developer.ken.so/reference/#kenso-api/tag/webhook-endpoints/DELETE/v1/webhook-endpoints/%7BwebhookEndpointId%7D)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `webhookEndpointId` | path | string | yes | The webhook endpoint's id, which starts with `ep_`. |
| `Ken-Version` | header | string, one of: 2026-11-02, 1.1 | no | The API version, a date in `YYYY-MM-DD` form. `1.1` is another name for the first dated version. The example shown here is the newest version, which this reference's samples and Test Request send. Leave it out to use your API key's pinned version. Keys created in the Kenso app are pinned to the newest version; keys minted by the CLI login are not. A key with no pinned version and no header gets the legacy shape where the path has one, and `404` where the path exists only in this version. A value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions. |
| `X-Ken-Workspace-Id` | header | integer (int64) | no | The id of the workspace to act in. Leave it out when your API key reaches only one workspace. When the key reaches more than one, a request without this header answers `400 workspace_required`. A workspace you are not a member of answers `404 not_found`. |

### Response 204

### Request

```bash
curl -X DELETE "https://api.ken.so/v1/webhook-endpoints/ep_2bX9kq4LmR7tW3vY" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"
```

### Example response

```http
HTTP/1.1 204 No Content
```

## Resend an endpoint's failed deliveries

`POST /v1/webhook-endpoints/{webhookEndpointId}/recover` - operationId `webhook-endpoints.recover`

| Permission | Rate limit |
| --- | --- |
| The `integrations` permission | 4,800 requests a minute per API key |

Resends every delivery to this endpoint that failed in a time window and never succeeded. Use it after your
endpoint was down.

`since` is required and at most 14 days ago. `until` defaults to now. Kenso runs the resends in the
background and answers `202` with the window. One call counts as 10 resends against the workspace's resend
limit of 30 a minute and 1,000 a day.

Errors:

- `400 validation_failed`: `since` is missing, more than 14 days ago or not before `until`, or
`until` is in the future.
- `404 not_found`: the workspace has no endpoint with this id.
- `429 rate_limited`: the workspace reached its resend limit. Wait and try again.

Requires the `integrations` permission.

[Try it on developer.ken.so](https://developer.ken.so/reference/#kenso-api/tag/webhook-endpoints/POST/v1/webhook-endpoints/%7BwebhookEndpointId%7D/recover)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `webhookEndpointId` | path | string | yes | The webhook endpoint's id, which starts with `ep_`. |
| `Ken-Version` | header | string, one of: 2026-11-02, 1.1 | no | The API version, a date in `YYYY-MM-DD` form. `1.1` is another name for the first dated version. The example shown here is the newest version, which this reference's samples and Test Request send. Leave it out to use your API key's pinned version. Keys created in the Kenso app are pinned to the newest version; keys minted by the CLI login are not. A key with no pinned version and no header gets the legacy shape where the path has one, and `404` where the path exists only in this version. A value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions. |
| `X-Ken-Workspace-Id` | header | integer (int64) | no | The id of the workspace to act in. Leave it out when your API key reaches only one workspace. When the key reaches more than one, a request without this header answers `400 workspace_required`. A workspace you are not a member of answers `404 not_found`. |

### Request body

`application/json`, optional.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `since` | string (date-time) | yes | Required. Start of the window, as an ISO 8601 time, at most 14 days ago. A time without a zone is read as UTC. |
| `until` | string (date-time) | no | End of the window, as an ISO 8601 time. Omitted: now. |

### Response 202

`data` is a `WebhookRecover`.

| Field | Type | Description |
| --- | --- | --- |
| `since` | string (date-time) | Start of the window, in UTC. |
| `until` | string (date-time) | End of the window, in UTC. |

### Request

```bash
curl -X POST "https://api.ken.so/v1/webhook-endpoints/ep_2bX9kq4LmR7tW3vY/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-10-12T00:00:00Z",
  "until": "2026-10-13T12:00:00Z"
}'
```

### Example response

```json
{
  "success": true,
  "data": {
    "since": "2026-10-12T00:00:00Z",
    "until": "2026-10-13T12:00:00Z"
  }
}
```

## Send a test event

`POST /v1/webhook-endpoints/{webhookEndpointId}/test` - operationId `webhook-endpoints.test`

| Permission | Rate limit |
| --- | --- |
| The `integrations` permission | 4,800 requests a minute per API key |

Sends the sample body of one event type to this endpoint only, and waits up to 5 seconds for the first attempt.
Use it to check that your endpoint receives and accepts Kenso's deliveries.

`eventType` can be any event type available to the workspace, or its alias, even one the endpoint does not
receive or filters out. It defaults to the first event type the endpoint receives, or `reply.received` when
the endpoint receives every type. A batched endpoint gets the `<type>.batch` sample of a high-volume
type, and `eventType` in the response says so. A `2026-12` endpoint gets the `2026-12` sample.

Errors:

- `400 validation_failed`: `eventType` is not available to the workspace.
- `404 not_found`: the workspace has no endpoint with this id.
- `409 invalid_state`: the endpoint is disabled. Enable it first.
- `429 rate_limited`: the workspace reached its limit of 30 test sends a minute or 1,000 a day. Wait the
seconds in `Retry-After` and try again.

Requires the `integrations` permission.

[Try it on developer.ken.so](https://developer.ken.so/reference/#kenso-api/tag/webhook-endpoints/POST/v1/webhook-endpoints/%7BwebhookEndpointId%7D/test)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `webhookEndpointId` | path | string | yes | The webhook endpoint's id, which starts with `ep_`. |
| `Ken-Version` | header | string, one of: 2026-11-02, 1.1 | no | The API version, a date in `YYYY-MM-DD` form. `1.1` is another name for the first dated version. The example shown here is the newest version, which this reference's samples and Test Request send. Leave it out to use your API key's pinned version. Keys created in the Kenso app are pinned to the newest version; keys minted by the CLI login are not. A key with no pinned version and no header gets the legacy shape where the path has one, and `404` where the path exists only in this version. A value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions. |
| `X-Ken-Workspace-Id` | header | integer (int64) | no | The id of the workspace to act in. Leave it out when your API key reaches only one workspace. When the key reaches more than one, a request without this header answers `400 workspace_required`. A workspace you are not a member of answers `404 not_found`. |

### Request body

`application/json`, optional.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `eventType` | string | no | The event type or its alias to send. Any type available to the workspace works, even one the endpoint does not receive. Omitted: the first type the endpoint receives, or `reply.received` when it receives every type. |

### Response 200

`data` is a `WebhookEndpointTest`.

| Field | Type | Description |
| --- | --- | --- |
| `messageId` | string | The id of the test message, a string that starts with `msg_`. |
| `eventType` | string | The event type Kenso sent. A batched endpoint gets `<type>.batch` for a high-volume type. |
| `attempt` | WebhookEndpointTestAttempt | The first delivery attempt, read for up to 5 seconds. Omitted when Kenso made none by then. |

### Request

```bash
curl -X POST "https://api.ken.so/v1/webhook-endpoints/ep_2bX9kq4LmR7tW3vY/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.classified"
}'
```

### Example response

```json
{
  "success": true,
  "data": {
    "messageId": "msg_2bKqB7dE9fG1hI3jK5lM7nO9pQ1",
    "eventType": "reply.classified",
    "attempt": {
      "status": "success",
      "responseStatusCode": 200,
      "occurredAt": "2026-10-14T09:44:03Z"
    }
  }
}
```

## Get an endpoint's signing secret

`GET /v1/webhook-endpoints/{webhookEndpointId}/signing-secret` - operationId `webhook-endpoints.get-signing-secret`

| Permission | Rate limit |
| --- | --- |
| The `integrations` permission | 60 requests a minute per API key |

Returns the secret that signs every delivery to this endpoint. Use it to check that a delivery came from
Kenso. Keep `secret` as private as a password.

Errors:

- `404 not_found`: the workspace has no endpoint with this id.

Requires the `integrations` permission.

[Try it on developer.ken.so](https://developer.ken.so/reference/#kenso-api/tag/webhook-endpoints/GET/v1/webhook-endpoints/%7BwebhookEndpointId%7D/signing-secret)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `webhookEndpointId` | path | string | yes | The webhook endpoint's id, which starts with `ep_`. |
| `Ken-Version` | header | string, one of: 2026-11-02, 1.1 | no | The API version, a date in `YYYY-MM-DD` form. `1.1` is another name for the first dated version. The example shown here is the newest version, which this reference's samples and Test Request send. Leave it out to use your API key's pinned version. Keys created in the Kenso app are pinned to the newest version; keys minted by the CLI login are not. A key with no pinned version and no header gets the legacy shape where the path has one, and `404` where the path exists only in this version. A value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions. |
| `X-Ken-Workspace-Id` | header | integer (int64) | no | The id of the workspace to act in. Leave it out when your API key reaches only one workspace. When the key reaches more than one, a request without this header answers `400 workspace_required`. A workspace you are not a member of answers `404 not_found`. |

### Response 200

`data` is a `WebhookSigningSecret`.

| Field | Type | Description |
| --- | --- | --- |
| `secret` | string | The signing secret. Keep it as private as a password. |

### Request

```bash
curl -X GET "https://api.ken.so/v1/webhook-endpoints/ep_2bX9kq4LmR7tW3vY/signing-secret" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"
```

### Example response

```json
{
  "success": true,
  "data": {
    "secret": "whsec_ZXhhbXBsZS1zaWduaW5nLXNlY3JldC1kby1ub3QtdXNl"
  }
}
```

## Rotate an endpoint's signing secret

`POST /v1/webhook-endpoints/{webhookEndpointId}/signing-secret/rotate` - operationId `webhook-endpoints.rotate-signing-secret`

| Permission | Rate limit |
| --- | --- |
| The `integrations` permission | 60 requests a minute per API key |

Gives the endpoint a new signing secret and returns it. Use it when a secret may have leaked, or on a schedule.

The previous secret keeps signing for 24 hours, until `previousSecretExpiresAt`. Until then every delivery
carries two signatures in `svix-signature`, one per secret, so a receiver that checks either secret accepts
it: deploy the new secret to your receiver within that window and no delivery fails verification. A second
rotate inside the window starts a new 24 hours for the secret it replaces.

Errors:

- `404 not_found`: the workspace has no endpoint with this id.
- `409 conflict`: the secret was already rotated 10 times in the last 24 hours. Rotate again once the oldest
previous secret expires.

Requires the `integrations` permission.

[Try it on developer.ken.so](https://developer.ken.so/reference/#kenso-api/tag/webhook-endpoints/POST/v1/webhook-endpoints/%7BwebhookEndpointId%7D/signing-secret/rotate)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `webhookEndpointId` | path | string | yes | The webhook endpoint's id, which starts with `ep_`. |
| `Ken-Version` | header | string, one of: 2026-11-02, 1.1 | no | The API version, a date in `YYYY-MM-DD` form. `1.1` is another name for the first dated version. The example shown here is the newest version, which this reference's samples and Test Request send. Leave it out to use your API key's pinned version. Keys created in the Kenso app are pinned to the newest version; keys minted by the CLI login are not. A key with no pinned version and no header gets the legacy shape where the path has one, and `404` where the path exists only in this version. A value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions. |
| `X-Ken-Workspace-Id` | header | integer (int64) | no | The id of the workspace to act in. Leave it out when your API key reaches only one workspace. When the key reaches more than one, a request without this header answers `400 workspace_required`. A workspace you are not a member of answers `404 not_found`. |

### Response 200

`data` is a `WebhookSigningSecretRotation`.

| Field | Type | Description |
| --- | --- | --- |
| `secret` | string | The new signing secret. Keep it as private as a password. |
| `previousSecretExpiresAt` | string (date-time) | When the previous secret stops signing deliveries, 24 hours after the rotate. Until then each delivery carries a signature from both secrets, so a receiver that checks either one accepts it. |

### Request

```bash
curl -X POST "https://api.ken.so/v1/webhook-endpoints/ep_2bX9kq4LmR7tW3vY/signing-secret/rotate" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"
```

### Example response

```json
{
  "success": true,
  "data": {
    "secret": "whsec_ZXhhbXBsZS1yb3RhdGVkLXNlY3JldC1kby1ub3QtdXNl",
    "previousSecretExpiresAt": "2026-10-14T09:30:00Z"
  }
}
```

## Types

Each named type the tables above use, nested ones included.

### WebhookLastDelivery

The newest delivery attempt to an endpoint.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `occurredAt` | string (date-time) | no | When Kenso made the attempt, in UTC. |
| `status` | string | no | The attempt's result: `success`, `pending` or `fail`. |
| `responseStatusCode` | integer (int32) | no | The HTTP status your endpoint answered. Omitted when it never answered. |
| `eventType` | string | no | The event type that was delivered. |

### WebhookEndpointTestAttempt

The first attempt to deliver a test event.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | string | no | The attempt's result: `success`, `pending` or `fail`. |
| `responseStatusCode` | integer (int32) | no | The HTTP status your endpoint answered. Omitted when it never answered. |
| `occurredAt` | string (date-time) | no | When Kenso made the attempt, in UTC. |

All resources: [/docs.md](/docs.md).
