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")).