Skip to Content
Integrations

Webhook endpoints

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

Integrations9 endpointsKen-Version: 2026-11-02AuthenticationWorkspacesErrorsWebhooks guide
MarkdownOpenAPI

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.

NameInTypeRequiredDescription
webhookEndpointIdpathstringrequiredThe 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.

NameInTypeRequiredDescription
Ken-Versionheaderstring, one of: 2026-11-02, 1.1optionalThe 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-Idheaderinteger (int64)optionalThe 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

GET/v1/webhook-endpointswebhook-endpoints.list
Permission
The integrations permission
Rate limit
12,000 requests a minute per API key

Try it on developer.ken.so

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

NameInTypeRequiredDescription
limitqueryinteger (int32)optionalEndpoints per page, from 1 to 200. Default 50.
cursorquerystringoptionalThe pagination.nextCursor of the previous page. Omit it for the first page.
Request
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

POST/v1/webhook-endpointswebhook-endpoints.create
Permission
The integrations permission
Rate limit
4,800 requests a minute per API key

Try it on developer.ken.so

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.

Request body

application/json, optional.

FieldTypeRequiredDescription
urlstringrequiredRequired. The https URL that receives events. It must resolve to a public address, and has at most 2,048 characters.
eventsarray of stringrequiredRequired. The event types the endpoint receives, at least one, from GET /v1/webhook-event-types. A type's alias names the same type.
descriptionstringoptionalYour own note about the endpoint, at most 500 characters.
appstringoptionalThe 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.
campaignIdsarray of integer (int64)optionalDeliver only events of these campaigns of the workspace. Omitted or empty: every campaign.
classificationsarray of stringoptionalDeliver only events whose reply has one of these classifications, in snake_case, such as interested. Omitted or empty: every classification.
isBatchedbooleanoptionalTrue to receive the high-volume event types in batches. Needs an events list. Default false.
schemaVersionstringoptionalThe 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.
Request
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

GET/v1/webhook-endpoints/{webhookEndpointId}webhook-endpoints.get
Permission
The integrations permission
Rate limit
12,000 requests a minute per API key

Try it on developer.ken.so

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.

Request
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

PATCH/v1/webhook-endpoints/{webhookEndpointId}webhook-endpoints.update
Permission
The integrations permission
Rate limit
4,800 requests a minute per API key

Try it on developer.ken.so

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.

Request body

application/json, optional.

FieldTypeRequiredDescription
urlstringoptionalA new https URL. It must resolve to a public address.
eventsarray of stringoptionalA new list of event types or their aliases, at least one. It replaces the current list.
descriptionstringoptionalA new note about the endpoint, at most 500 characters.
isDisabledbooleanoptionalTrue pauses delivery to the endpoint. False resumes it.
appstringoptionalThe app the endpoint belongs to: zapier, make or n8n. An empty string clears it.
campaignIdsarray of integer (int64)optionalA new campaign filter that replaces the current one. Empty means every campaign.
classificationsarray of stringoptionalA new classification filter, in snake_case, that replaces the current one. Empty means every classification.
isBatchedbooleanoptionalTrue to receive the high-volume event types in batches, false to receive them one by one.
schemaVersionstringoptionalA new payload schema, 2026-11 or 2026-12, with the same rules as on create.
Request
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

DELETE/v1/webhook-endpoints/{webhookEndpointId}webhook-endpoints.delete
Permission
The integrations permission
Rate limit
4,800 requests a minute per API key

Try it on developer.ken.so

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.

Request
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

Response 204
HTTP/1.1 204 No Content

Get an endpoint's signing secret

GET/v1/webhook-endpoints/{webhookEndpointId}/signing-secretwebhook-endpoints.get-signing-secret
Permission
The integrations permission
Rate limit
60 requests a minute per API key

Try it on developer.ken.so

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.

Request
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

POST/v1/webhook-endpoints/{webhookEndpointId}/signing-secret/rotatewebhook-endpoints.rotate-signing-secret
Permission
The integrations permission
Rate limit
60 requests a minute per API key

Try it on developer.ken.so

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.

Request
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

POST/v1/webhook-endpoints/{webhookEndpointId}/recoverwebhook-endpoints.recover
Permission
The integrations permission
Rate limit
4,800 requests a minute per API key

Try it on developer.ken.so

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.

Request body

application/json, optional.

FieldTypeRequiredDescription
sincestring (date-time)requiredRequired. Start of the window, as an ISO 8601 time, at most 14 days ago. A time without a zone is read as UTC.
untilstring (date-time)optionalEnd of the window, as an ISO 8601 time. Omitted: now.
Request
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

POST/v1/webhook-endpoints/{webhookEndpointId}/testwebhook-endpoints.test
Permission
The integrations permission
Rate limit
4,800 requests a minute per API key

Try it on developer.ken.so

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 is a developer sandbox and 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.

Request body

application/json, optional.

FieldTypeRequiredDescription
eventTypestringoptionalThe 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.
Request
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.


On this page