Event subscriptions
Event webhook subscriptions for MCP clients: create, renew, list and remove.
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 |
|---|---|---|---|---|
eventSubscriptionId | path | string | required | The subscription id, a string that starts with sub_. |
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 your event subscriptions
/v1/event-subscriptionsevent-subscriptions.list- Permission
- Any workspace member except a Network member
- Rate limit
- 12,000 requests a minute per API key
Returns your own subscriptions in the workspace, newest first. Expired and ended subscriptions stay in the list for 7 days. The signing secret is never returned.
Errors:
403 forbidden: the API key is not tied to a member.
Open to any workspace member.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
limit | query | integer (int32) | optional | Subscriptions 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/event-subscriptions?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 EventSubscription. Each item has these fields. The response also carries pagination.
Show the 10 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Get an event subscription
/v1/event-subscriptions/{eventSubscriptionId}event-subscriptions.get- Permission
- Any workspace member except a Network member
- Rate limit
- 12,000 requests a minute per API key
Returns one of your subscriptions with its status and delivery health. The signing secret is never returned.
Errors:
403 forbidden: the API key is not tied to a member.404 not_found: you have no subscription with this id.
Open to any workspace member.
curl -X GET "https://api.ken.so/v1/event-subscriptions/sub_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 EventSubscription.
Show the 10 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Delete an event subscription
/v1/event-subscriptions/{eventSubscriptionId}event-subscriptions.delete- Permission
- The
integrationspermission - Rate limit
- 4,800 requests a minute per API key
Deletes one of your subscriptions. Kenso stops its deliveries at once and deletes its signing secret.
Errors:
403 forbidden: the API key is not tied to a member.404 not_found: you have no subscription with this id. Another member's subscription is not found either.
Requires the integrations permission.
curl -X DELETE "https://api.ken.so/v1/event-subscriptions/sub_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 ContentCreate or renew an event subscription
/v1/event-subscriptionsevent-subscriptions.upsert- Permission
- The
integrationspermission - Rate limit
- 600 requests a minute per API key
Subscribes a URL to one event type, or renews the matching subscription you already have. Kenso matches on you, name, arguments and delivery.url. A match is renewed and answers 200. Anything else creates a subscription and answers 201.
name is an event type with mcp set to true in GET /v1/webhook-event-types, and you must be able to see its page. arguments narrows the events with campaignId or classification, where the type supports them. delivery.mode is webhook. delivery.url uses https, resolves to a public address and has at most 2,048 characters. delivery.secret is whsec_ followed by the base64 of 24 to 64 random bytes. Kenso stores the secret encrypted and never returns it, and a renewal can replace it.
Kenso checks the first subscription to a URL. It POSTs a signed {"type":"verification","challenge":"..."} body, and the URL must answer with a 2xx status and {"challenge":"..."} holding the same value.
The subscription lasts ttlMs, from one minute to one hour, and one hour when you omit it. Subscribe again before refreshBefore, or it expires. cursor sets where delivery starts for a new or lapsed subscription, and no cursor starts now. maxAgeMs limits how far back that start can be. A live subscription keeps its own position. A workspace holds at most 50 active subscriptions.
Errors:
400 validation_failed: a required field is missing, ordelivery.url,delivery.secret,arguments,cursorormaxAgeMsis invalid.400 unsupported:nameis not in the event log, ordelivery.modeis notwebhook.400 callback_verification_failed: the URL did not pass the check.error.details[0].codesays why:connection_refused,timeout,tls_error,http_4xx,http_5xxorchallenge_failed.403 forbidden: the API key is not tied to a member, or you cannot see the page of this event type.404 not_found: event subscriptions are not on for the workspace, ornameis unknown.409 resource_exhausted: the workspace already has 50 active subscriptions. Delete one first.
Requires the integrations permission.
Request body
application/json, optional.
| Field | Type | Required | Description |
|---|---|---|---|
name | string | required | Required. The event type, such as meeting.booked. It must have mcp set to true in GET /v1/webhook-event-types. |
arguments | map of object | optional | Filters for the events: campaignId or classification, where the event type supports them. Omitted: no filter. |
delivery | EventSubscriptionDeliveryRequest | required | Required. Where and how Kenso delivers the events. |
cursor | string | optional | Where delivery starts for a new or lapsed subscription, as a cursor from the event log. Omitted: now. Ignored on a live subscription. |
maxAgeMs | integer (int64) | optional | Start delivery no earlier than this many milliseconds ago. |
ttlMs | integer (int64) | optional | How long the subscription lasts, in milliseconds, from one minute to one hour. Omitted: one hour. |
curl -X POST "https://api.ken.so/v1/event-subscriptions" \
-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 '{
"name": "meeting.booked",
"arguments": {
"key": null
},
"delivery": {
"mode": "webhook",
"url": "https://example.com",
"secret": "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw"
},
"cursor": "eyJpZCI6ODE1fQ",
"maxAgeMs": 1,
"ttlMs": 1
}'Response 201
Also answers 200. data is a EventSubscriptionGrant.
Show the 5 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Unsubscribe by event and URL
/v1/event-subscriptions/unsubscribeevent-subscriptions.unsubscribe- Permission
- The
integrationspermission - Rate limit
- 4,800 requests a minute per API key
Deletes the subscription whose name, arguments and delivery.url match yours exactly. Use it when you know what you subscribed to but not the subscription id. Kenso stops its deliveries at once and deletes its signing secret.
Errors:
400 validation_failed:nameordelivery.urlis missing, orargumentsis invalid.403 forbidden: the API key is not tied to a member.404 not_found: none of your subscriptions match.
Requires the integrations permission.
Request body
application/json, optional.
| Field | Type | Required | Description |
|---|---|---|---|
name | string | required | Required. The subscription's event type. |
arguments | map of object | optional | The subscription's filters, exactly as you sent them on create. Omitted: no filter. |
delivery | EventSubscriptionUnsubscribeDelivery | required | Required. The subscription's delivery URL. |
curl -X POST "https://api.ken.so/v1/event-subscriptions/unsubscribe" \
-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 '{
"name": "string",
"arguments": {
"key": null
},
"delivery": {
"url": "https://example.com"
}
}'Response 204
HTTP/1.1 204 No ContentMore in Integrations:Webhook endpointsWebhook deliveriesWebhook event typesEventsInbound webhooksCRM connectionsCRM syncCRM field mappingsCRM fieldsCRM importsCRM listsCRM pipelinesCRM recordsCRM sync issuesTriggersTrigger firingsTrigger schemasEvent logAll resources