Skip to Content
Integrations

Inbound webhooks

Webhook URLs on a campaign that send leads into Kenso from your own tools, with field mapping and recent deliveries.

Integrations10 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
inboundWebhookIdpathinteger (int64)requiredThe inbound webhook's id.

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 a campaign's inbound webhooks

GET/v1/campaigns/{campaignId}/inbound-webhooksinbound-webhooks.list
Permission
The integrations permission
Rate limit
12,000 requests a minute per API key

Try it on developer.ken.so

Returns the inbound webhooks that add contacts to one campaign, ordered by id.

Errors:

  • 400 validation_failed: limit or cursor is invalid.
  • 404 not_found: the campaign is not in the workspace.

Requires the integrations permission.

Parameters

NameInTypeRequiredDescription
campaignIdpathinteger (int64)requiredThe campaign whose webhooks to list.
limitqueryinteger (int32)optionalWebhooks 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/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

POST/v1/campaigns/{campaignId}/inbound-webhooksinbound-webhooks.create
Permission
The integrations permission
Rate limit
4,800 requests a minute per API key

Try it on developer.ken.so

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: name is missing or too long, the preset is unknown, the mapping is invalid, the sample is too large, kind is not campaign, or the body has a people webhook field.
  • 404 not_found: the campaign is not in the workspace.

Requires the integrations permission.

Parameters

NameInTypeRequiredDescription
campaignIdpathinteger (int64)requiredThe campaign the webhook adds contacts to.

Request body

application/json, optional.

FieldTypeRequiredDescription
namestringrequiredRequired. The webhook's name, from 1 to 120 characters.
samplePayloadJsonstringoptionalAn example body from the sending tool, at most 64 KB, kept to help build and test the mapping.
mappingarray of WebhookAssignmentoptionalThe rules that turn a delivery's JSON into Kenso fields, at most 60. Omitted: the preset's mapping.
presetstringoptionalA ready-made mapping for a known tool: hubspot_forms, typeform, webflow, tally, rb2b, vector, generic, zapier, make or n8n. Used when mapping is empty.
kindstringoptionalThe 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.
appstringoptionalA people webhook only: the sending app, zapier, make or n8n. The zapier, make and n8n presets set it.
defaultOwnerMemberIdinteger (int64)optionalA people webhook only: the member who owns the people it creates. Omitted: the workspace's intake settings decide.
createAccountsbooleanoptionalA people webhook only: false never creates an account for the person's company. true or omitted: the workspace's intake settings decide.
Request
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

GET/v1/inbound-webhooks/{inboundWebhookId}inbound-webhooks.get
Permission
The integrations permission
Rate limit
12,000 requests a minute per API key

Try it on developer.ken.so

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.

Request
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

PATCH/v1/inbound-webhooks/{inboundWebhookId}inbound-webhooks.update
Permission
The integrations permission
Rate limit
4,800 requests a minute per API key

Try it on developer.ken.so

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].field names the field, and error.details[0].code is invalid_member for 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.

FieldTypeRequiredDescription
namestringoptionalA new name, from 1 to 120 characters.
samplePayloadJsonstringoptionalA new example body, at most 64 KB.
mappingarray of WebhookAssignmentoptionalA new mapping that replaces the current one, at most 60 entries.
statusstringoptionalThe webhook's status: active or paused. Kenso refuses deliveries to a paused webhook.
appstringoptionalA people webhook only: zapier, make or n8n, or null to clear it.
defaultOwnerMemberIdinteger (int64)optionalA people webhook only: a member of the workspace who owns the people it creates, or null to clear it.
createAccountsbooleanoptionalA people webhook only: false never creates an account for the person's company. true lets the workspace's intake settings decide.
createPersonbooleanoptionalA workflow webhook only: whether each delivery also creates or updates a person when the workflow's webhook trigger does not say.
Request
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

DELETE/v1/inbound-webhooks/{inboundWebhookId}inbound-webhooks.delete
Permission
The integrations permission
Rate limit
4,800 requests a minute per API key

Try it on developer.ken.so

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.

Request
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

Response 204
HTTP/1.1 204 No Content

List people webhooks

GET/v1/inbound-webhooksinbound-webhooks.list-people-sources
Permission
The integrations permission
Rate limit
12,000 requests a minute per API key
Needs the 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.

Try it on developer.ken.so

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: limit or cursor is invalid.

Requires the integrations permission.

Parameters

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

POST/v1/inbound-webhooksinbound-webhooks.create-people-source
Permission
The integrations permission
Rate limit
4,800 requests a minute per API key
Needs the 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.

Try it on developer.ken.so

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: name is missing or too long, the mapping is missing or invalid, the sample is too large, kind is not people, app is unknown or differs from the preset's app, or defaultOwnerMemberId is not a member. error.details[0].code is unknown_preset for an unknown preset and invalid_member for an owner outside the workspace.

Requires the integrations permission.

Request body

application/json, optional.

FieldTypeRequiredDescription
namestringrequiredRequired. The webhook's name, from 1 to 120 characters.
samplePayloadJsonstringoptionalAn example body from the sending tool, at most 64 KB, kept to help build and test the mapping.
mappingarray of WebhookAssignmentoptionalThe rules that turn a delivery's JSON into Kenso fields, at most 60. Omitted: the preset's mapping.
presetstringoptionalA ready-made mapping for a known tool: hubspot_forms, typeform, webflow, tally, rb2b, vector, generic, zapier, make or n8n. Used when mapping is empty.
kindstringoptionalThe 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.
appstringoptionalA people webhook only: the sending app, zapier, make or n8n. The zapier, make and n8n presets set it.
defaultOwnerMemberIdinteger (int64)optionalA people webhook only: the member who owns the people it creates. Omitted: the workspace's intake settings decide.
createAccountsbooleanoptionalA people webhook only: false never creates an account for the person's company. true or omitted: the workspace's intake settings decide.
Request
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

POST/v1/inbound-webhooks/{inboundWebhookId}/rotate-tokeninbound-webhooks.rotate-token
Permission
The integrations permission
Rate limit
200 requests a minute per API key

Try it on developer.ken.so

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.

Request
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

POST/v1/inbound-webhooks/{inboundWebhookId}/test-mappinginbound-webhooks.test-mapping
Permission
The integrations permission
Rate limit
4,800 requests a minute per API key

Try it on developer.ken.so

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, and company_domain or company_name.
  • people: email, profile_url, or a name with company_domain.
  • website: the mapping maps company_domain or email, and the sample fills email, profile_url or company_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: samplePayloadJson is 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.

FieldTypeRequiredDescription
samplePayloadJsonstringrequiredRequired. An example body from the sending tool, as a JSON string of at most 64 KB.
mappingarray of WebhookAssignmentoptionalThe mapping to run on the sample.
Request
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

GET/v1/inbound-webhooks/{inboundWebhookId}/deliveriesinbound-webhooks.deliveries
Permission
The integrations permission
Rate limit
12,000 requests a minute per API key

Try it on developer.ken.so

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: limit is out of range.
  • 404 not_found: the workspace has no inbound webhook with this id.

Requires the integrations permission.

Parameters

NameInTypeRequiredDescription
limitqueryinteger (int32)optionalHow many recent deliveries to return, from 1 to 100. Default 100.
Request
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.


On this page