Webhook endpoints
Endpoints Kenso posts events to: register them, read their signing secret, send a test and resend failed deliveries.
Path parameters
The endpoints whose path names one of these take it as described here. An endpoint's own table lists a path parameter only when it describes it differently.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
webhookEndpointId | path | string | required | The webhook endpoint's id, which starts with ep_. |
Headers
The endpoints on this page take these headers. Each endpoint's curl shows the ones it sends.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
Ken-Version | header | string, one of: 2026-11-02, 1.1 | optional | 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 date that is not a version answers 400 unsupported_version; any other value that is not a version is treated as legacy. |
X-Ken-Workspace-Id | header | integer (int64) | optional | 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. |
List webhook endpoints
/v1/webhook-endpointswebhook-endpoints.list- Permission
- The
integrationspermission - Rate limit
- 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.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
limit | query | integer (int32) | optional | Endpoints per page, from 1 to 200. Default 50. |
cursor | query | string | optional | The pagination.nextCursor of the previous page. Omit it for the first page. |
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"Response 200
data is a list of WebhookEndpoint. Each item has these fields. The response also carries pagination.
Show the 14 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Create a webhook endpoint
/v1/webhook-endpointswebhook-endpoints.create- Permission
- The
integrationspermission - Rate limit
- 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:urlis missing, not https or not public, an event type is unknown to the workspace,appor a classification is unknown, the filter is too large, batch delivery is not available to the workspace yet, orschemaVersionis unknown or not available to the workspace yet. Also forschemaVersion2026-12while another enabled endpoint has noeventslist: give that endpoint aneventslist first.404 not_found: a campaign incampaignIdsis not in the workspace.409 conflict: the workspace already has 25 endpoints. Delete one first.
Requires the integrations permission.
Request body
application/json, optional.
| Field | Type | Required | Description |
|---|---|---|---|
url | string | required | 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 | required | 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 | optional | Your own note about the endpoint, at most 500 characters. |
app | string | optional | 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) | optional | Deliver only events of these campaigns of the workspace. Omitted or empty: every campaign. |
classifications | array of string | optional | Deliver only events whose reply has one of these classifications, in snake_case, such as interested. Omitted or empty: every classification. |
isBatched | boolean | optional | True to receive the high-volume event types in batches. Needs an events list. Default false. |
schemaVersion | string | optional | 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. |
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
}'Response 201
data is a WebhookEndpoint.
Show the 14 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Get a webhook endpoint
/v1/webhook-endpoints/{webhookEndpointId}webhook-endpoints.get- Permission
- The
integrationspermission - Rate limit
- 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.
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"Response 200
data is a WebhookEndpoint.
Show the 14 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Update a webhook endpoint
/v1/webhook-endpoints/{webhookEndpointId}webhook-endpoints.update- Permission
- The
integrationspermission - Rate limit
- 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 incampaignIdsis not in the workspace.
Requires the integrations permission.
Request body
application/json, optional.
| Field | Type | Required | Description |
|---|---|---|---|
url | string | optional | A new https URL. It must resolve to a public address. |
events | array of string | optional | A new list of event types or their aliases, at least one. It replaces the current list. |
description | string | optional | A new note about the endpoint, at most 500 characters. |
isDisabled | boolean | optional | True pauses delivery to the endpoint. False resumes it. |
app | string | optional | The app the endpoint belongs to: zapier, make or n8n. An empty string clears it. |
campaignIds | array of integer (int64) | optional | A new campaign filter that replaces the current one. Empty means every campaign. |
classifications | array of string | optional | A new classification filter, in snake_case, that replaces the current one. Empty means every classification. |
isBatched | boolean | optional | True to receive the high-volume event types in batches, false to receive them one by one. |
schemaVersion | string | optional | A new payload schema, 2026-11 or 2026-12, with the same rules as on create. |
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
}'Response 200
data is a WebhookEndpoint.
Show the 14 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Delete a webhook endpoint
/v1/webhook-endpoints/{webhookEndpointId}webhook-endpoints.delete- Permission
- The
integrationspermission - Rate limit
- 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.
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"Response 204
HTTP/1.1 204 No ContentGet an endpoint's signing secret
/v1/webhook-endpoints/{webhookEndpointId}/signing-secretwebhook-endpoints.get-signing-secret- Permission
- The
integrationspermission - Rate limit
- 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.
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"Response 200
data is a WebhookSigningSecret.
Show the 1 response field and an example
The fields and an example are also on this endpoint's Markdown page.
Rotate an endpoint's signing secret
/v1/webhook-endpoints/{webhookEndpointId}/signing-secret/rotatewebhook-endpoints.rotate-signing-secret- Permission
- The
integrationspermission - Rate limit
- 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.
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"Response 200
data is a WebhookSigningSecretRotation.
Show the 2 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Resend an endpoint's failed deliveries
/v1/webhook-endpoints/{webhookEndpointId}/recoverwebhook-endpoints.recover- Permission
- The
integrationspermission - Rate limit
- 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:sinceis missing, more than 14 days ago or not beforeuntil, oruntilis 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.
Request body
application/json, optional.
| Field | Type | Required | Description |
|---|---|---|---|
since | string (date-time) | required | 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) | optional | End of the window, as an ISO 8601 time. Omitted: now. |
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"
}'Response 202
data is a WebhookRecover.
Show the 2 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Send a test event
/v1/webhook-endpoints/{webhookEndpointId}/testwebhook-endpoints.test- Permission
- The
integrationspermission - Rate limit
- 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:eventTypeis 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 is a developer sandbox and reached its limit of 30 test sends a minute or 1,000 a day. Wait the seconds inRetry-Afterand try again.
Requires the integrations permission.
Request body
application/json, optional.
| Field | Type | Required | Description |
|---|---|---|---|
eventType | string | optional | 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. |
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"
}'Response 200
data is a WebhookEndpointTest.
Show the 3 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
More in Integrations:Webhook deliveriesWebhook event typesEventsInbound webhooksCRM connectionsCRM syncCRM field mappingsCRM fieldsCRM importsCRM listsCRM pipelinesCRM recordsCRM sync issuesTriggersTrigger firingsTrigger schemasEvent subscriptionsEvent logAll resources