Event subscriptions

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

Webhooks and events5 endpointsKen-Version: 2026-11-02Authentication Workspaces Errors

List your MCP event webhook subscriptions in the current workspace

GET/v1/event-subscriptionsevent-subscriptions.list

Try it on developer.ken.so

Only your own, newest first; expired and terminated ones stay listed for 7 days. The signing secret is never returned.

Parameters

Name

Type

Required

Description

Limit

In: query

integer (int32)

optional

Cursor

In: query

string

optional

Ken-Version

In: header

string, one of: 2026-11-02, 1.1

required

The API version: a dated version (YYYY-MM-DD), or 1.1, another name for the first dated version. Without it the request uses your API key's pinned version; an unpinned key reaches the legacy shape of the same path. 1.0 selects the legacy shape explicitly.

X-Ken-Workspace-Id

In: header

integer (int64)

optional

Workspace to act in. Required when your credential can reach more than one workspace (otherwise 400 workspace_required).

Response 200

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

Field

Type

Description

string

name

string

The event type.

arguments

object

The filters it was made with (campaignId, classification).

url

string

Where it delivers.

status

string

active, expired or terminated.

refreshBefore

string (date-time)

verifiedAt

string (date-time)

deliveryStatus

EventDeliveryStatusModel

SEP-3415 deliveryStatus. lastError is a category, never the endpoint's own text.

createdAt

string (date-time)

updatedAt

string (date-time)

Request

curl -X GET "https://api.ken.so/v1/event-subscriptions" \
  -H "Authorization: Bearer $KEN_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KEN_WORKSPACE_ID"

Response 200

{
  "success": true,
  "data": [
    {
      "id": "string",
      "name": "string",
      "arguments": null,
      "url": "https://example.com",
      "status": "string",
      "refreshBefore": "2026-09-23T15:02:11Z",
      "verifiedAt": "2026-09-23T15:02:11Z",
      "deliveryStatus": {
        "active": true,
        "lastDeliveryAt": "2026-09-23T15:02:11Z",
        "lastError": "string",
        "failedSince": "2026-09-23T15:02:11Z"
      },
      "createdAt": "2026-09-23T15:02:11Z",
      "updatedAt": "2026-09-23T15:02:11Z"
    }
  ],
  "pagination": {
    "nextCursor": "eyJpZCI6ODE1fQ",
    "hasMore": true,
    "total": 1,
    "isTotalCapped": true
  }
}

Create or renew an MCP event webhook subscription

POST/v1/event-subscriptionsevent-subscriptions.upsert

Try it on developer.ken.so

Requires the integrations feature and the event group's page; a machine key without a member is 403. Keyed by (you, delivery.url, name, arguments): the same key renews (200), a new one creates (201). delivery.mode is webhook; delivery.url is https and must resolve to a public address; delivery.secret is whsec_ + base64 of 24 to 64 random bytes, stored encrypted and never returned (a renewal may rotate it). The first subscription to a URL POSTs a signed {"type":"verification","challenge":...} and needs {"challenge":...} echoed in a 2xx body, else callback_verification_failed with the category in error.details[0].code. The grant (refreshBefore) is at most one hour: subscribe again before it. cursor starts a new or lapsed subscription there (null: now; maxAgeMs bounds the replay); a live one keeps its own. At most 50 active subscriptions per workspace (resource_exhausted). 404 when MCP events are not enabled for the workspace.

Parameters

Name

Type

Required

Description

Ken-Version

In: header

string, one of: 2026-11-02, 1.1

required

X-Ken-Workspace-Id

In: header

integer (int64)

optional

Workspace to act in. Required when your credential can reach more than one workspace (otherwise 400 workspace_required).

Request body

application/json, optional.

Field

Type

Required

Description

name

string

optional

The MCP event type, such as meeting.booked.

arguments

map of object

optional

The event's filters: campaignId, classification, as the type supports them.

delivery

EventSubscriptionDeliveryRequest

optional

cursor

string

optional

Where delivery starts for a new or lapsed subscription. Null: from now. Ignored on a live one.

maxAgeMs

integer (int64)

optional

Start no earlier than this many milliseconds ago.

ttlMs

integer (int64)

optional

The suggested lifetime in milliseconds. The grant is at most one hour.

Response 201

Also answers 200. data is a EventSubscriptionGrantModel.

Field

Type

Description

string

The subscription id, sent as X-MCP-Subscription-Id on every delivery.

refreshBefore

string (date-time)

Subscribe again with the same key before this time, or the subscription expires.

cursor

string

The safe-to-persist watermark: every event at or before it was delivered or given up on.

truncated

boolean

Delivery starts later than the cursor you supplied: events were skipped.

deliveryStatus

EventDeliveryStatusModel

SEP-3415 deliveryStatus. lastError is a category, never the endpoint's own text.

Request

curl -X POST "https://api.ken.so/v1/event-subscriptions" \
  -H "Authorization: Bearer $KEN_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KEN_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "string",
  "arguments": {
    "key": null
  },
  "delivery": {
    "mode": "string",
    "url": "https://example.com",
    "secret": "string"
  },
  "cursor": "eyJpZCI6ODE1fQ",
  "maxAgeMs": 1,
  "ttlMs": 1
}'

Response 201

{
  "success": true,
  "data": {
    "id": "string",
    "refreshBefore": "2026-09-23T15:02:11Z",
    "cursor": "eyJpZCI6ODE1fQ",
    "truncated": true,
    "deliveryStatus": {
      "active": true,
      "lastDeliveryAt": "2026-09-23T15:02:11Z",
      "lastError": "string",
      "failedSince": "2026-09-23T15:02:11Z"
    }
  }
}

Get one of your MCP event webhook subscriptions

GET/v1/event-subscriptions/{eventSubscriptionId}event-subscriptions.get

Try it on developer.ken.so

Parameters

Name

Type

Required

Description

eventSubscriptionId

In: path

string

required

Ken-Version

In: header

string, one of: 2026-11-02, 1.1

required

X-Ken-Workspace-Id

In: header

integer (int64)

optional

Workspace to act in. Required when your credential can reach more than one workspace (otherwise 400 workspace_required).

Response 200

data is a EventSubscriptionModel.

Field

Type

Description

string

name

string

The event type.

arguments

object

The filters it was made with (campaignId, classification).

url

string

Where it delivers.

status

string

active, expired or terminated.

refreshBefore

string (date-time)

verifiedAt

string (date-time)

deliveryStatus

EventDeliveryStatusModel

SEP-3415 deliveryStatus. lastError is a category, never the endpoint's own text.

createdAt

string (date-time)

updatedAt

string (date-time)

Request

curl -X GET "https://api.ken.so/v1/event-subscriptions/string" \
  -H "Authorization: Bearer $KEN_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KEN_WORKSPACE_ID"

Response 200

{
  "success": true,
  "data": {
    "id": "string",
    "name": "string",
    "arguments": null,
    "url": "https://example.com",
    "status": "string",
    "refreshBefore": "2026-09-23T15:02:11Z",
    "verifiedAt": "2026-09-23T15:02:11Z",
    "deliveryStatus": {
      "active": true,
      "lastDeliveryAt": "2026-09-23T15:02:11Z",
      "lastError": "string",
      "failedSince": "2026-09-23T15:02:11Z"
    },
    "createdAt": "2026-09-23T15:02:11Z",
    "updatedAt": "2026-09-23T15:02:11Z"
  }
}

Delete one of your MCP event webhook subscriptions

DELETE/v1/event-subscriptions/{eventSubscriptionId}event-subscriptions.delete

Try it on developer.ken.so

Requires the integrations feature. Deliveries stop at once and the signing secret is deleted. Another member's subscription is not found.

Parameters

Name

Type

Required

Description

eventSubscriptionId

In: path

string

required

Ken-Version

In: header

string, one of: 2026-11-02, 1.1

required

X-Ken-Workspace-Id

In: header

integer (int64)

optional

Workspace to act in. Required when your credential can reach more than one workspace (otherwise 400 workspace_required).

Response 204

Request

curl -X DELETE "https://api.ken.so/v1/event-subscriptions/string" \
  -H "Authorization: Bearer $KEN_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KEN_WORKSPACE_ID"

Response 204

HTTP/1.1 204 No Content

Unsubscribe by event, arguments and URL

POST/v1/event-subscriptions/unsubscribeevent-subscriptions.unsubscribe

Try it on developer.ken.so

SEP-3415 events/unsubscribe: name, arguments and delivery.url must match one of your subscriptions exactly, else 404. Requires the integrations feature. Deliveries stop at once and the signing secret is deleted.

Parameters

Name

Type

Required

Description

Ken-Version

In: header

string, one of: 2026-11-02, 1.1

required

X-Ken-Workspace-Id

In: header

integer (int64)

optional

Workspace to act in. Required when your credential can reach more than one workspace (otherwise 400 workspace_required).

Request body

application/json, optional.

Field

Type

Required

Description

name

string

optional

arguments

map of object

optional

delivery

EventSubscriptionUnsubscribeDelivery

optional

Response 204

Request

curl -X POST "https://api.ken.so/v1/event-subscriptions/unsubscribe" \
  -H "Authorization: Bearer $KEN_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KEN_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 Content

More in Webhooks and events:Webhook endpoints Webhook deliveries Webhook event types Events Event occurrences Inbound webhooks Triggers Trigger firings Trigger schemas All resources