Inbound webhooks
Webhook URLs on a campaign that send leads into Kenso from your own tools, with field mapping and recent deliveries.
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 |
|---|---|---|---|---|
inboundWebhookId | path | integer (int64) | required | The inbound webhook's id. |
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 a campaign's inbound webhooks
/v1/campaigns/{campaignId}/inbound-webhooksinbound-webhooks.list- Permission
- The
integrationspermission - Rate limit
- 12,000 requests a minute per API key
Returns the inbound webhooks that add contacts to one campaign, ordered by id.
Errors:
400 validation_failed:limitorcursoris invalid.404 not_found: the campaign is not in the workspace.
Requires the integrations permission.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
campaignId | path | integer (int64) | required | The campaign whose webhooks to list. |
limit | query | integer (int32) | optional | Webhooks 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/campaigns/812/inbound-webhooks?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 InboundWebhook. Each item has these fields. The response also carries pagination.
Show the 17 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Create a campaign inbound webhook
/v1/campaigns/{campaignId}/inbound-webhooksinbound-webhooks.create- Permission
- The
integrationspermission - Rate limit
- 4,800 requests a minute per API key
Creates a webhook whose deliveries add contacts to this campaign. The response has the webhook's url, which holds its secret token, and a Location header.
name is required, from 1 to 120 characters. Send a mapping, or a preset that fills the mapping: hubspot_forms, typeform, webflow, tally, rb2b, vector, generic, zapier, make or n8n. A mapping you send wins over the preset's. samplePayloadJson is an example body of at most 64 KB. app, defaultOwnerMemberId and createAccounts belong to people webhooks, and kind can only be campaign here.
Errors:
400 validation_failed:nameis missing or too long, the preset is unknown, the mapping is invalid, the sample is too large,kindis notcampaign, or the body has a people webhook field.404 not_found: the campaign is not in the workspace.
Requires the integrations permission.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
campaignId | path | integer (int64) | required | The campaign the webhook adds contacts to. |
Request body
application/json, optional.
| Field | Type | Required | Description |
|---|---|---|---|
name | string | required | Required. The webhook's name, from 1 to 120 characters. |
samplePayloadJson | string | optional | An example body from the sending tool, at most 64 KB, kept to help build and test the mapping. |
mapping | array of WebhookAssignment | optional | The rules that turn a delivery's JSON into Kenso fields, at most 60. Omitted: the preset's mapping. |
preset | string | optional | A ready-made mapping for a known tool: hubspot_forms, typeform, webflow, tally, rb2b, vector, generic, zapier, make or n8n. Used when mapping is empty. |
kind | string | optional | The webhook's kind, campaign or people. Optional, because the route decides it: campaign under a campaign and people at the workspace level. A different value is refused with 400. |
app | string | optional | A people webhook only: the sending app, zapier, make or n8n. The zapier, make and n8n presets set it. |
defaultOwnerMemberId | integer (int64) | optional | A people webhook only: the member who owns the people it creates. Omitted: the workspace's intake settings decide. |
createAccounts | boolean | optional | A people webhook only: false never creates an account for the person's company. true or omitted: the workspace's intake settings decide. |
curl -X POST "https://api.ken.so/v1/campaigns/812/inbound-webhooks" \
-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",
"samplePayloadJson": "string",
"mapping": [
{
"target": "first_name",
"variableName": "string",
"useAsAiContext": true,
"fallback": true,
"source": {
"kind": "path",
"path": "data.contact.email",
"value": "string",
"labelPath": "field.title",
"valuePath": "string",
"label": "Email",
"labelsPath": "string",
"idPath": "string",
"index": 1
}
}
],
"preset": "hubspot_forms",
"kind": "string",
"app": "string",
"defaultOwnerMemberId": 812,
"createAccounts": true
}'Response 201
data is a InboundWebhook.
Show the 17 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Get an inbound webhook
/v1/inbound-webhooks/{inboundWebhookId}inbound-webhooks.get- Permission
- The
integrationspermission - Rate limit
- 12,000 requests a minute per API key
Returns one inbound webhook of any kind, with its URL, mapping, status and delivery counts.
Errors:
404 not_found: the workspace has no inbound webhook with this id.
Requires the integrations permission.
curl -X GET "https://api.ken.so/v1/inbound-webhooks/812" \
-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 InboundWebhook.
Show the 17 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Update an inbound webhook
/v1/inbound-webhooks/{inboundWebhookId}inbound-webhooks.update- Permission
- The
integrationspermission - Rate limit
- 4,800 requests a minute per API key
Changes the fields you send. Omitted fields keep their values, and the URL does not change.
Every kind takes name, samplePayloadJson, mapping and status. status is active or paused, and Kenso refuses deliveries to a paused webhook. A people webhook also takes app (zapier, make or n8n, or null to clear it), defaultOwnerMemberId (a member of the workspace, or null to clear it) and createAccounts, and keeps its preset and people counts. A workflow webhook also takes createPerson. Any other kind refuses these fields.
The mapping must map what the webhook's kind needs: a campaign webhook first_name, last_name and company_domain or company_name; a people webhook email, profile_url, or a name with company_domain; a website webhook company_domain or email. A workflow or signal webhook's mapping needs no field and may be empty: a workflow run gets whatever the mapping finds, and a signal webhook reads deliveries with its vendor's reader, not its mapping. Publishing a workflow replaces its webhook's mapping with the one on its webhook trigger.
A website webhook follows the visitor-ID provider set for your website in Settings, Integrations. The next PATCH /v1/website that names a provider resumes it and resets its mapping to that provider's preset. Set the provider to none to stop it.
Errors:
400 validation_failed: a field has the wrong type or value, the mapping is invalid, the sample is larger than 64 KB, or the field does not fit the webhook's kind.error.details[0].fieldnames the field, anderror.details[0].codeisinvalid_memberfor an owner outside the workspace.404 not_found: the workspace has no inbound webhook with this id.
Requires the integrations permission.
Request body
application/json, optional.
| Field | Type | Required | Description |
|---|---|---|---|
name | string | optional | A new name, from 1 to 120 characters. |
samplePayloadJson | string | optional | A new example body, at most 64 KB. |
mapping | array of WebhookAssignment | optional | A new mapping that replaces the current one, at most 60 entries. |
status | string | optional | The webhook's status: active or paused. Kenso refuses deliveries to a paused webhook. |
app | string | optional | A people webhook only: zapier, make or n8n, or null to clear it. |
defaultOwnerMemberId | integer (int64) | optional | A people webhook only: a member of the workspace who owns the people it creates, or null to clear it. |
createAccounts | boolean | optional | A people webhook only: false never creates an account for the person's company. true lets the workspace's intake settings decide. |
createPerson | boolean | optional | A workflow webhook only: whether each delivery also creates or updates a person when the workflow's webhook trigger does not say. |
curl -X PATCH "https://api.ken.so/v1/inbound-webhooks/812" \
-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",
"samplePayloadJson": "string",
"mapping": [
{
"target": "first_name",
"variableName": "string",
"useAsAiContext": true,
"fallback": true,
"source": {
"kind": "path",
"path": "data.contact.email",
"value": "string",
"labelPath": "field.title",
"valuePath": "string",
"label": "Email",
"labelsPath": "string",
"idPath": "string",
"index": 1
}
}
],
"status": "active",
"app": "zapier",
"defaultOwnerMemberId": 812,
"createAccounts": true,
"createPerson": true
}'Response 200
data is a InboundWebhook.
Show the 17 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Delete an inbound webhook
/v1/inbound-webhooks/{inboundWebhookId}inbound-webhooks.delete- Permission
- The
integrationspermission - Rate limit
- 4,800 requests a minute per API key
Deletes the inbound webhook. Kenso stops accepting deliveries to its URL. Contacts and people it already created stay.
Errors:
404 not_found: the workspace has no inbound webhook with this id.
Requires the integrations permission.
curl -X DELETE "https://api.ken.so/v1/inbound-webhooks/812" \
-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 ContentList people webhooks
/v1/inbound-webhooksinbound-webhooks.list-people-sources- Permission
- The
integrationspermission - Rate limit
- 12,000 requests a minute per API key
accounts feature on your workspace. Until it is on, calls answer 404. Needs the lead_intake feature on your workspace. Until it is on, calls answer 404.Returns the workspace's people webhooks, ordered by id. Each delivery to a people webhook creates or updates a person, with the source form for the form presets, visitor for rb2b and vector, and webhook otherwise. A campaign's webhooks are listed under the campaign.
Errors:
400 validation_failed:limitorcursoris invalid.
Requires the integrations permission.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
limit | query | integer (int32) | optional | Webhooks 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/inbound-webhooks?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 InboundWebhook. Each item has these fields. The response also carries pagination.
Show the 17 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Create a people webhook
/v1/inbound-webhooksinbound-webhooks.create-people-source- Permission
- The
integrationspermission - Rate limit
- 4,800 requests a minute per API key
accounts feature on your workspace. Until it is on, calls answer 404. Needs the lead_intake feature on your workspace. Until it is on, calls answer 404.Creates a workspace webhook whose deliveries create or update a person. The response has the webhook's url, which holds its secret token, and a Location header.
name is required, from 1 to 120 characters. Send a preset, an app or a mapping. The presets are hubspot_forms, typeform, webflow, tally, rb2b, vector, generic, zapier, make and n8n. The zapier, make and n8n presets read the generic flat keys and set app, and an app with no preset or mapping reads them too. A mapping you send wins over the preset's, and must map an email, a profile_url, or a name together with a company_domain.
defaultOwnerMemberId must be a member of the workspace. createAccounts: false never creates the person's account.
Errors:
400 validation_failed:nameis missing or too long, the mapping is missing or invalid, the sample is too large,kindis notpeople,appis unknown or differs from the preset's app, ordefaultOwnerMemberIdis not a member.error.details[0].codeisunknown_presetfor an unknown preset andinvalid_memberfor an owner outside the workspace.
Requires the integrations permission.
Request body
application/json, optional.
| Field | Type | Required | Description |
|---|---|---|---|
name | string | required | Required. The webhook's name, from 1 to 120 characters. |
samplePayloadJson | string | optional | An example body from the sending tool, at most 64 KB, kept to help build and test the mapping. |
mapping | array of WebhookAssignment | optional | The rules that turn a delivery's JSON into Kenso fields, at most 60. Omitted: the preset's mapping. |
preset | string | optional | A ready-made mapping for a known tool: hubspot_forms, typeform, webflow, tally, rb2b, vector, generic, zapier, make or n8n. Used when mapping is empty. |
kind | string | optional | The webhook's kind, campaign or people. Optional, because the route decides it: campaign under a campaign and people at the workspace level. A different value is refused with 400. |
app | string | optional | A people webhook only: the sending app, zapier, make or n8n. The zapier, make and n8n presets set it. |
defaultOwnerMemberId | integer (int64) | optional | A people webhook only: the member who owns the people it creates. Omitted: the workspace's intake settings decide. |
createAccounts | boolean | optional | A people webhook only: false never creates an account for the person's company. true or omitted: the workspace's intake settings decide. |
curl -X POST "https://api.ken.so/v1/inbound-webhooks" \
-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",
"samplePayloadJson": "string",
"mapping": [
{
"target": "first_name",
"variableName": "string",
"useAsAiContext": true,
"fallback": true,
"source": {
"kind": "path",
"path": "data.contact.email",
"value": "string",
"labelPath": "field.title",
"valuePath": "string",
"label": "Email",
"labelsPath": "string",
"idPath": "string",
"index": 1
}
}
],
"preset": "hubspot_forms",
"kind": "string",
"app": "string",
"defaultOwnerMemberId": 812,
"createAccounts": true
}'Response 201
data is a InboundWebhook.
Show the 17 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Rotate an inbound webhook's token
/v1/inbound-webhooks/{inboundWebhookId}/rotate-tokeninbound-webhooks.rotate-token- Permission
- The
integrationspermission - Rate limit
- 200 requests a minute per API key
Gives the webhook a new secret token, so its url changes. The old URL stops working at once, so update the sending tool with the new url from the response. Use it when the URL leaked.
Errors:
404 not_found: the workspace has no inbound webhook with this id.
Requires the integrations permission.
curl -X POST "https://api.ken.so/v1/inbound-webhooks/812/rotate-token" \
-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 InboundWebhook.
Show the 17 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Test a mapping on a sample body
/v1/inbound-webhooks/{inboundWebhookId}/test-mappinginbound-webhooks.test-mapping- Permission
- The
integrationspermission - Rate limit
- 4,800 requests a minute per API key
Runs a mapping on a sample body and returns the result, without creating a contact or person and without saving the mapping. Use it to check a mapping before you save it with PATCH /v1/inbound-webhooks/{inboundWebhookId}.
Send samplePayloadJson and mapping. Kenso checks the mapping with the rules of this webhook's kind. The response lists the fields and custom variables the mapping filled, the paths it could not find, and whether Kenso would accept the delivery.
On every kind, each mapping row needs a known target and a payload path or constant. Each kind also has the rule a real delivery meets:
campaign:first_name,last_name, andcompany_domainorcompany_name.people:email,profile_url, or a name withcompany_domain.website: the mapping mapscompany_domainoremail, and the sample fillsemail,profile_urlorcompany_domain.workflow: no required field, and the mapping may be empty. Every delivery starts a run with the fields the mapping finds.signal: the mapping is not used. The sample must be a payload the webhook's vendor sends.
Errors:
400 validation_failed:samplePayloadJsonis missing, larger than 64 KB or not valid JSON.404 not_found: the workspace has no inbound webhook with this id.
Requires the integrations permission.
Request body
application/json, optional.
| Field | Type | Required | Description |
|---|---|---|---|
samplePayloadJson | string | required | Required. An example body from the sending tool, as a JSON string of at most 64 KB. |
mapping | array of WebhookAssignment | optional | The mapping to run on the sample. |
curl -X POST "https://api.ken.so/v1/inbound-webhooks/812/test-mapping" \
-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 '{
"samplePayloadJson": "string",
"mapping": [
{
"target": "first_name",
"variableName": "string",
"useAsAiContext": true,
"fallback": true,
"source": {
"kind": "path",
"path": "data.contact.email",
"value": "string",
"labelPath": "field.title",
"valuePath": "string",
"label": "Email",
"labelsPath": "string",
"idPath": "string",
"index": 1
}
}
]
}'Response 200
data is a InboundWebhookMappingTest.
Show the 5 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
List an inbound webhook's deliveries
/v1/inbound-webhooks/{inboundWebhookId}/deliveriesinbound-webhooks.deliveries- Permission
- The
integrationspermission - Rate limit
- 12,000 requests a minute per API key
Returns the most recent deliveries to the webhook, with what Kenso did with each one and why. Use it to find out why a sending tool's data did not arrive.
limit is from 1 to 100, default 100. This list has one page and no cursor.
Errors:
400 validation_failed:limitis out of range.404 not_found: the workspace has no inbound webhook with this id.
Requires the integrations permission.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
limit | query | integer (int32) | optional | How many recent deliveries to return, from 1 to 100. Default 100. |
curl -X GET "https://api.ken.so/v1/inbound-webhooks/812/deliveries?limit=100" \
-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 InboundWebhookDelivery. Each item has these fields. The response also carries pagination.
Show the 5 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
More in Integrations:Webhook endpointsWebhook deliveriesWebhook event typesEventsCRM connectionsCRM syncCRM field mappingsCRM fieldsCRM importsCRM listsCRM pipelinesCRM recordsCRM sync issuesTriggersTrigger firingsTrigger schemasEvent subscriptionsEvent logAll resources