Kenso MCP tools

Webhooks webhooks

Call it from an MCP client connected to https://mcp.ken.so/mcp: reads go through webhooks_read and changes through webhooks_write. Each takes operation plus that operation's parameters, and your workspace role decides which operations you see.

Each operation with a route calls the Kenso API at https://api.ken.so with Authorization: Bearer <Kenso API key>, Ken-Version: 1.1 and X-Ken-Workspace-Id: <workspace id>. You can call that route directly with the same headers.

Operations: inbound-webhooks-create, create, inbound-webhooks-delete, delete, deliveries, inbound-webhooks-get, get, get-signing-secret, inbound-webhooks-list, webhook-deliveries-list, list, resend, rotate-token, test, test-mapping, inbound-webhooks-update, update

inbound-webhooks-create

Write. POST https://api.ken.so/v1/campaigns/{campaignId}/inbound-webhooks

Path: campaignId

Body (json): app string, createAccounts boolean, defaultOwnerMemberId integer, kind string, mapping array, name string, preset string, samplePayloadJson string

Create an inbound webhook on a campaign. Public. Requires the integrations permission (admins by default). Returns the ingest url.

POST /api/v1/campaigns/{campaignId}/inbound-webhooks. Public. Sends Ken-Version 1.1.
Requires the integrations permission (admins by default). The workspace is X-Ken-Workspace-Id. The API returns 201.
name is required and at most 120 characters. samplePayloadJson and mapping
are optional; samplePayloadJson is a JSON object or a JSON string, sent as
a JSON string. Each mapping item has target, variableName, useAsAiContext,
and source (kind path, constant or label, plus path or value; label reads
the array at path for the element whose labelPath equals label and takes
its valuePath; an index limits it to that position, skipping a field
another label row found). preset is optional: hubspot_forms, typeform, webflow,
tally, rb2b or vector fills the mapping for that form vendor's payload,
and generic, zapier, make or n8n for flat keys (email, first_name,
last_name, full_name, company, company_domain, title, phone,
linkedin_url), when mapping is empty (an explicit mapping wins). A campaign
outside the workspace is not_found before the create. status starts active.
To create people instead of campaign leads, use
people(operation="create-people-source").

create

Write. POST https://api.ken.so/v1/webhook-endpoints

Body (json): app string, campaignIds array, classifications array, description string, events array, isBatched boolean, url string

Create a webhook endpoint. Public. Requires full access. events is a non-empty list of event types.

POST /api/v1/webhook-endpoints. Sends Ken-Version 1.1 and X-Ken-Workspace-Id.
Returns 201. api_keys(operation="webhook-event-types-list") lists every type the workspace can
subscribe to, with its group, filters and a sample body; the API refuses any other name.
Event types are case-sensitive on the API: reply.received, meeting.booked,
touch.approved, touch.sent, signal.detected, asset.viewed, opportunity.created,
opportunity.stage_changed (stageCategory open, won or lost says whether the deal was won or lost),
role_candidate.stage_changed (a recruiting candidate moved stage; recruiting workspaces only),
call.logged (a call with a person was logged; ids and outcome only, no numbers or notes),
the campaign events email_sent, lead_replied, lead_interested, lead_unsubscribed, lead_clicked, reply_opened,
and the workflow events workflow_run_failed, workflow_run_needs_attention,
workflow_published, workflow_limit_reached.
Zapier, Make and n8n connect by creating an endpoint with their catch-hook URL.
app (zapier, make or n8n) tags the endpoint; omitted, it is read from the URL host
(hooks.zapier.com, *.make.com, n8n cloud or an n8n host). Every endpoint returns app, null when none.
campaign_ids (workspace campaigns; another workspace's id is not_found) delivers only events of those
campaigns, and classifications (snake_case reply.classified labels: interested, not_interested, ...)
only events whose reply has one of them. Both set: both must match. A filtered endpoint never receives
an event without that dimension. At most 10 campaigns, 10 labels, or campaigns times labels up to 10.
is_batched true delivers the high-volume types (highVolume in the event catalog) as <type>.batch
deliveries of up to 100 events, flushed within about a minute, never one by one. It needs an events
list and is validation_failed while batch delivery is not on for the workspace.
Every endpoint returns campaignIds, classifications and isBatched.

inbound-webhooks-delete

Write. DELETE https://api.ken.so/v1/inbound-webhooks/{inboundWebhookId}

Path: inboundWebhookId

Delete an inbound webhook. Public. Requires the integrations permission (admins by default). Returns 204.

DELETE /api/v1/inbound-webhooks/{inboundWebhookId}. Public. Sends Ken-Version 1.1.
Requires the integrations permission (admins by default). Returns 204. The workspace is X-Ken-Workspace-Id.
A webhook outside the workspace is not_found before the delete.

delete

Write. DELETE https://api.ken.so/v1/webhook-endpoints/{webhookEndpointId}

Path: webhookEndpointId

Delete a webhook endpoint. Public. Requires full access. Returns 204.

DELETE /api/v1/webhook-endpoints/{webhookEndpointId}. Sends Ken-Version 1.1.
webhook_endpoint_id is a Svix ep_ string.

deliveries

Read. GET https://api.ken.so/v1/inbound-webhooks/{inboundWebhookId}/deliveries

Path: inboundWebhookId

Query: limit integer

List recent deliveries for an inbound webhook. Public. limit is 1 to 100. There is no cursor and no totalCount.

GET /api/v1/inbound-webhooks/{inboundWebhookId}/deliveries. Public.
Sends Ken-Version 1.1. Requires the `integrations` permission. The workspace is
X-Ken-Workspace-Id. Deliveries have no numeric id, so this is a window of
at most 100. limit is 1 to 100. Omit it for the server default of 100.
There is no cursor and no totalCount. A webhook outside the workspace is
not_found before the window is read.

inbound-webhooks-get

Read. GET https://api.ken.so/v1/inbound-webhooks/{inboundWebhookId}

Path: inboundWebhookId

Return one inbound webhook. Public. A webhook outside the workspace is not_found.

GET /api/v1/inbound-webhooks/{inboundWebhookId}. Public. Sends Ken-Version 1.1.
Requires the `integrations` permission. status is active or paused. url is the ingest URL.
samplePayloadJson and lastReceivedAt are omitted when absent.
A webhook outside the workspace is not_found.

get

Read. GET https://api.ken.so/v1/webhook-endpoints/{webhookEndpointId}

Path: webhookEndpointId

Get one webhook endpoint. Public. An id outside the workspace is not_found.

GET /api/v1/webhook-endpoints/{webhookEndpointId}. Sends Ken-Version 1.1.
webhook_endpoint_id is a Svix ep_ string. Requires the `integrations` permission.

get-signing-secret

Read. GET https://api.ken.so/v1/webhook-endpoints/{webhookEndpointId}/signing-secret

Path: webhookEndpointId

Read the webhook signing secret. Treat the value as a credential. Public exposure. The API requires full access.

GET /api/v1/webhook-endpoints/{webhookEndpointId}/signing-secret.
Sends Ken-Version 1.1 and X-Ken-Workspace-Id. Requires the integrations permission (admins by default).

inbound-webhooks-list

Read. GET https://api.ken.so/v1/campaigns/{campaignId}/inbound-webhooks

Path: campaignId

Query: cursor string, limit integer

List a campaign's inbound webhooks, ordered by id. Public. There is no totalCount. status is active or paused.

GET /api/v1/campaigns/{campaignId}/inbound-webhooks. Public. Sends Ken-Version 1.1.
Requires the `integrations` permission. The workspace is X-Ken-Workspace-Id. Pages use limit
(1 to 200) and cursor, ordered by id. Omit limit for the server default.
There is no totalCount. status is active or paused. url is the ingest URL.
samplePayloadJson and lastReceivedAt are omitted when absent. There is no
clientId. A campaign outside the workspace is not_found before the list.
The token, deliveries and mapping test are webhooks(operation="rotate-token"),
"deliveries" and "test-mapping".

webhook-deliveries-list

Read. GET https://api.ken.so/v1/webhook-endpoints/{webhookEndpointId}/deliveries

Path: webhookEndpointId

Query: cursor string, limit integer

List deliveries for one webhook endpoint. Public. cursor is the provider cursor, not an endpoint-list cursor.

GET /api/v1/webhook-endpoints/{webhookEndpointId}/deliveries.
Sends Ken-Version 1.1. Requires the `integrations` permission. limit is 1 to 200.

list

Read. GET https://api.ken.so/v1/webhook-endpoints

Query: cursor string, limit integer

List webhook endpoints in the current workspace. Public. Endpoint ids are Svix ep_ strings. Each endpoint carries its health.

GET /api/v1/webhook-endpoints. Sends Ken-Version 1.1 and X-Ken-Workspace-Id.
Requires the `integrations` permission. limit is 1 to 200. cursor is the provider page cursor.
health is active, failing (the newest attempt failed) or disabled. lastDelivery has
occurredAt, status (success, pending, fail), responseStatusCode and eventType.
failedAttempts counts failures since the newest success among the latest 10 attempts.
The three fields are left out when the delivery log could not be read.

resend

Write. POST https://api.ken.so/v1/webhook-endpoints/{webhookEndpointId}/deliveries/{deliveryId}/resend

Path: webhookEndpointId, deliveryId

Resend one webhook delivery. Public. Requires full access. delivery_id is a delivery's id or its messageId.

POST /api/v1/webhook-endpoints/{webhookEndpointId}/deliveries/{deliveryId}/resend.
Sends Ken-Version 1.1 and X-Ken-Workspace-Id.
delivery_id takes either value from a webhook-deliveries list row: its id (atmpt_...)
or its messageId (msg_...). An id is looked up among the endpoint's newest 1,000
deliveries; an older or unknown one is not_found, so resend an older delivery by its
messageId. data.deliveryId echoes the value sent.

rotate-token

Write. POST https://api.ken.so/v1/inbound-webhooks/{inboundWebhookId}/rotate-token

Path: inboundWebhookId

Rotate an inbound webhook ingest token. Public. Requires the integrations permission (admins by default). The previous URL stops immediately.

POST /api/v1/inbound-webhooks/{inboundWebhookId}/rotate-token. Public.
Sends Ken-Version 1.1. Requires the integrations permission (admins by default). The workspace is
X-Ken-Workspace-Id. The previous url stops working immediately. The
response includes the new url. A webhook outside the workspace is not_found
before the rotate.

test

Write. POST https://api.ken.so/v1/webhook-endpoints/{webhookEndpointId}/test

Path: webhookEndpointId

Body (json): eventType string

Send a test event to one webhook endpoint and report the first attempt. Public. Requires full access. Only this endpoint receives it.

POST /api/v1/webhook-endpoints/{webhookEndpointId}/test. Sends Ken-Version 1.1 and
X-Ken-Workspace-Id. Delivers the example payload of event_type (marked "test": true).
event_type is any type available to the workspace (api_keys(operation="webhook-event-types-list")),
whether or not the endpoint receives it or filters by campaign or classification. It defaults to
the first event the endpoint receives, reply.received when it receives every event. A batched
endpoint gets a high-volume type's <type>.batch example, and eventType in the result says so. A type
the workspace cannot use is validation_failed, and a disabled endpoint is invalid_state. Waits up to
5 seconds and returns messageId, eventType and attempt (status success, pending or fail,
responseStatusCode, occurredAt), or no attempt when Svix had not tried yet.

test-mapping

Write. POST https://api.ken.so/v1/inbound-webhooks/{inboundWebhookId}/test-mapping

Path: inboundWebhookId

Body (json): mapping array, samplePayloadJson string

Dry-run an inbound webhook mapping. This does not create a lead. Public. Requires the integrations permission (admins by default).

POST /api/v1/inbound-webhooks/{inboundWebhookId}/test-mapping. Public.
Sends Ken-Version 1.1. Requires the integrations permission (admins by default). The workspace is
X-Ken-Workspace-Id. This does not create a lead. The result has
resolvedFields, resolvedCustomVariables, unresolvedPaths, wouldBeAccepted,
and rejectionReason. A webhook outside the workspace is not_found first.

inbound-webhooks-update

Write. PATCH https://api.ken.so/v1/inbound-webhooks/{inboundWebhookId}

Path: inboundWebhookId

Body (json): app string, createAccounts boolean, createPerson boolean, defaultOwnerMemberId integer, mapping array, name string, samplePayloadJson string, status string

Update an inbound webhook. Absent fields stay unchanged. Public. Requires the integrations permission (admins by default). status is active or paused. A people webhook also takes app, defaultOwnerMemberId and createAccounts.

PATCH /api/v1/inbound-webhooks/{inboundWebhookId}. Public. Sends Ken-Version 1.1.
Requires the integrations permission (admins by default). The workspace is X-Ken-Workspace-Id. Fields are name,
samplePayloadJson, mapping, status, app, defaultOwnerMemberId,
createAccounts and createPerson (snake_case keys work too). samplePayloadJson
is a JSON object or a JSON string. status is active
or paused. A paused source rejects new ingest. Absent fields stay unchanged.
A people webhook (kind people) also takes app (zapier, make or n8n, or null
to clear it), defaultOwnerMemberId (a workspace member, else invalid_member;
null clears it, so the intake settings decide the owner) and createAccounts
(true or false). Its URL, preset, peopleCreated and peopleUpdated stay.
Another kind refuses those three with validation_failed naming the field.
createPerson belongs to a workflow webhook, which a workflow sets on its
webhook trigger; this route refuses it the same way. Null is rejected for
every field but app and defaultOwnerMemberId.
The mapping must map what the kind needs: campaign first_name, last_name
and company_domain or company_name; people email, profile_url, or a name
with company_domain; website company_domain or email. A workflow or signal
webhook's mapping needs no field and may be empty (a signal webhook reads
deliveries with its vendor's reader, not its mapping). Publishing a
workflow replaces its webhook's mapping with its webhook trigger's.
A webhook outside the workspace is not_found before the write. A website
source (kind website) follows the site's visitor-ID provider, set in
Settings > Integrations: the next website update that names a provider
resumes it and resets its mapping to that provider's preset. To stop it,
set the site's provider to none.

update

Write. PATCH https://api.ken.so/v1/webhook-endpoints/{webhookEndpointId}

Path: webhookEndpointId

Body (json): app string, campaignIds array, classifications array, description string, events array, isBatched boolean, isDisabled boolean, url string

Update a webhook endpoint. Omitted fields stay unchanged. is_disabled true pauses delivery and false resumes it. Requires full access.

PATCH /api/v1/webhook-endpoints/{webhookEndpointId}. Sends Ken-Version 1.1.
Null events leaves subscriptions unchanged. An empty events list is rejected.
app (zapier, make or n8n) sets the app tag; an empty string clears it, so the URL host decides again.
campaign_ids and classifications replace that filter; an empty list clears it, and the one omitted
keeps its value. is_batched turns batch delivery of the high-volume types on or off (see
webhooks(operation="create")).