Skip to Content
Integrations

Event subscriptions

Event webhook subscriptions for MCP clients: create, renew, list and remove.

Integrations5 endpointsKen-Version: 2026-11-02AuthenticationWorkspacesErrors
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
eventSubscriptionIdpathstringrequiredThe 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.

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 your event subscriptions

GET/v1/event-subscriptionsevent-subscriptions.list
Permission
Any workspace member except a Network member
Rate limit
12,000 requests a minute per API key

Try it on developer.ken.so

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

NameInTypeRequiredDescription
limitqueryinteger (int32)optionalSubscriptions 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/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

GET/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

Try it on developer.ken.so

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.

Request
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

DELETE/v1/event-subscriptions/{eventSubscriptionId}event-subscriptions.delete
Permission
The integrations permission
Rate limit
4,800 requests a minute per API key

Try it on developer.ken.so

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.

Request
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

Response 204
HTTP/1.1 204 No Content

Create or renew an event subscription

POST/v1/event-subscriptionsevent-subscriptions.upsert
Permission
The integrations permission
Rate limit
600 requests a minute per API key

Try it on developer.ken.so

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, or delivery.url, delivery.secret, arguments, cursor or maxAgeMs is invalid.
  • 400 unsupported: name is not in the event log, or delivery.mode is not webhook.
  • 400 callback_verification_failed: the URL did not pass the check. error.details[0].code says why: connection_refused, timeout, tls_error, http_4xx, http_5xx or challenge_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, or name is unknown.
  • 409 resource_exhausted: the workspace already has 50 active subscriptions. Delete one first.

Requires the integrations permission.

Request body

application/json, optional.

FieldTypeRequiredDescription
namestringrequiredRequired. The event type, such as meeting.booked. It must have mcp set to true in GET /v1/webhook-event-types.
argumentsmap of objectoptionalFilters for the events: campaignId or classification, where the event type supports them. Omitted: no filter.
deliveryEventSubscriptionDeliveryRequestrequiredRequired. Where and how Kenso delivers the events.
cursorstringoptionalWhere delivery starts for a new or lapsed subscription, as a cursor from the event log. Omitted: now. Ignored on a live subscription.
maxAgeMsinteger (int64)optionalStart delivery no earlier than this many milliseconds ago.
ttlMsinteger (int64)optionalHow long the subscription lasts, in milliseconds, from one minute to one hour. Omitted: one hour.
Request
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

POST/v1/event-subscriptions/unsubscribeevent-subscriptions.unsubscribe
Permission
The integrations permission
Rate limit
4,800 requests a minute per API key

Try it on developer.ken.so

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: name or delivery.url is missing, or arguments is 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.

FieldTypeRequiredDescription
namestringrequiredRequired. The subscription's event type.
argumentsmap of objectoptionalThe subscription's filters, exactly as you sent them on create. Omitted: no filter.
deliveryEventSubscriptionUnsubscribeDeliveryrequiredRequired. The subscription's delivery URL.
Request
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

Response 204
HTTP/1.1 204 No Content

On this page