> For the complete documentation index, see [llms.txt](https://developer.kizen.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.kizen.com/docs/concepts/agentic-workflows/agentic-workflow-triggers/webhook-triggers.md).

# Webhook Triggers

Learn how Kizen's Webhook trigger works, including how to configure inbound requests and extract data for use in Agentic Workflows.

{% hint style="success" %}
**Audience:** Administrators, Solution Architects, and Developers

**Purpose:** Documents the Webhook trigger in <code class="expression">space.vars.Kizen\_company\_name</code>: how it works, how data is extracted from inbound requests, and the behavioral details that affect how webhook-triggered <code class="expression">space.vars.automations</code> are designed and debugged.
{% endhint %}

## Overview

The Webhook trigger initiates an <code class="expression">space.vars.automation</code> via an inbound HTTP request from an external system. Each webhook trigger generates a unique URL that external tools and services can call directly to start an <code class="expression">space.vars.automation</code> execution.

***

## Webhook URL

Each Webhook trigger is assigned a unique URL based on the webhook name configured at setup.

<div data-with-frame="true"><figure><img src="https://3898351136-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQd8ufpN7wkdnx7JtgoeZ%2Fuploads%2FpecfEIJ9mqCgwM5VwfhO%2FScreenshot%202026-03-31%20at%2011.30.23%E2%80%AFAM.png?alt=media&amp;token=75cfec1a-c84c-43a1-966e-89b2bad72a44" alt="" width="246"><figcaption></figcaption></figure></div>

&#x20;The URL follows this format:

```
https://app.go.kizen.com/api/automations/{webhook-name}/webhook/{webhook-name}
```

The webhook name is user-defined and becomes part of the URL. Choose a name that clearly identifies the <code class="expression">space.vars.automation</code> and integration context. It can't be changed after the trigger is saved without breaking existing integrations.

***

## POST and GET Requests

The webhook trigger supports both POST and GET requests. The selected method determines which data extraction options are available.

### POST

**POST** requests support a request body payload. When POST is selected, the trigger configuration exposes an example Payload field, a Content-Type selector, and data extraction options for both the request body and URL query string.

#### Content-Types

When using POST, the Content-Type of the inbound request can be set to match the format sent by the external system. Supported content types include:

* `application/json`
* `application/javascript`
* `application/xml`
* `application/xhtml+xml`
* `application/x-www-form-urlencoded`
* `text/plain`
* `text/html`
* `text/xml`
* `text/csv`

### GET

**GET** requests do not include a request body. When GET is selected, only URL query string extraction is available.

***

## Record Identifier Requirements

Inbound webhook requests must include a <code class="expression">space.vars.entity</code> identifier so <code class="expression">space.vars.Kizen\_company\_name</code> can associate the request with the correct <code class="expression">space.vars.entity</code> and initiate the <code class="expression">space.vars.automation</code> in the appropriate context. The <code class="expression">space.vars.entity</code> identifier is required only for <code class="expression">space.vars.entity</code>-based <code class="expression">space.vars.automations</code>, not global ones.

***

## Authentication and Permissions

Every webhook call runs as a <code class="expression">space.vars.Kizen\_company\_name</code> user. Before the <code class="expression">space.vars.automation</code> starts, <code class="expression">space.vars.Kizen\_company\_name</code> checks that user's permissions, so the account attempting to authenticate decides whether the call succeeds.

### Authenticate the Caller

The webhook endpoint requires an authenticated, active user in the business. Most integrations authenticate with an API key tied to a service account, which lets you grant only the access the <code class="expression">space.vars.automation</code> needs rather than exposing broad admin permissions to an external system.

### Permission Rules

The following rules apply to every webhook call, whether the caller is a standard user account or a service account authenticated with an API key:

* The caller must be an active user in the business. An inactive or unauthenticated caller can't start an <code class="expression">space.vars.automation</code>.
* A Global <code class="expression">space.vars.automation</code> (An <code class="expression">space.vars.automation</code> that is not tied to a <code class="expression">space.vars.entity</code>) needs no permission beyond active membership in the business.
* A <code class="expression">space.vars.entity</code>-based <code class="expression">space.vars.automation</code> needs the same permissions required to start that <code class="expression">space.vars.automation</code> manually on the <code class="expression">space.vars.entity</code>. Specifically, it needs permission to start <code class="expression">space.vars.automations</code> on the <code class="expression">space.vars.object</code>, plus View access to the target <code class="expression">space.vars.entity</code>.

| Agentic Workflow type                                                    | What the caller needs                                                                                                                                                                                                                      |
| ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Global (not tied to a <code class="expression">space.vars.entity</code>) | An active user in the business. No additional permission.                                                                                                                                                                                  |
| <code class="expression">space.vars.entity</code>-based                  | An active user, plus permission to modify <code class="expression">space.vars.automations</code> on the <code class="expression">space.vars.object</code> and View access to the target <code class="expression">space.vars.entity</code>. |

### When a Call is Denied

If the caller doesn't have the required permissions for a <code class="expression">space.vars.entity</code>-based <code class="expression">space.vars.automation</code>, the endpoint returns a `403` response with this message:&#x20;

```
You do not have permission to start this Agentic Workflow on this Record.
```

To resolve the issue, give the caller View access to the <code class="expression">space.vars.entity</code> and confirm the account can start <code class="expression">space.vars.automations</code> on that <code class="expression">space.vars.object</code>, then retry the call.

{% hint style="warning" %}
Avoid using an over-permissioned account to authenticate. <code class="expression">space.vars.automations</code> run with elevated access regardless of who triggers them, so external callers only need permission to start the <code class="expression">space.vars.workflow</code>, not broad admin rights. <code class="expression">space.vars.Kizen\_company\_name</code> recommends a dedicated service account scoped to exactly what the <code class="expression">space.vars.workflow</code> requires: active membership for Global <code class="expression">space.vars.automations</code> and record access for <code class="expression">space.vars.entity</code>-based ones.
{% endhint %}

***

## Data Extraction

The Data Extraction section controls what information is pulled from the inbound request and made available as variable sources within the <code class="expression">space.vars.automation</code>. Available options differ by request method.

* **JSON Path** *(POST only).* Individual values can be extracted from the request body using JSONPath expressions. Each extraction row requires a JSON Path expression, a Name that becomes the variable identifier downstream, and optionally an Example Payload to preview the extracted value at configuration time. Rows can be added manually with **+ Add Value** or generated automatically from the Example Payload using **Generate Values Automatically**. *This is only applicable if the content-type is JSON.*
* **Extract Full Body Content** *(POST only).* When enabled, the full request body is extracted and made available as a variable source. Use this when the entire payload is needed downstream rather than specific fields.
* **Extract URL Query String** *(POST and GET).* When enabled, values from the URL query string are extracted and made available as variable sources. This option is available for both POST and GET requests.

All extracted values flow into the <code class="expression">space.vars.automation</code>'s variable system and can be referenced by any subsequent step that supports variable inputs.

***

## Webhook Triggers Cannot Fail Directly

The Webhook trigger itself does not fail. <code class="expression">space.vars.Kizen\_company\_name</code> always accepts the inbound request regardless of what the payload contains.

If a required <code class="expression">space.vars.automation</code> variable depends on a value not present in the payload, the failure surfaces at the variable evaluation stage and not at the trigger. When debugging a webhook-triggered <code class="expression">space.vars.automation</code> that is not behaving as expected, check variable initialization first.

***

## What's Next?

Now that you understand how each trigger type works, continue to [Agentic Workflow Code Steps](/docs/concepts/agentic-workflows/automation-code-steps.md) to learn learn how to run custom Python scripts within an <code class="expression">space.vars.automation</code> to handle complex logic, external API calls, and data transformations that go beyond built-in actions.

<details>

<summary>Related Topics</summary>

* [Agentic Workflow Triggers](/docs/concepts/agentic-workflows/agentic-workflow-triggers.md)
* [Action-Based Triggers](/docs/concepts/agentic-workflows/agentic-workflow-triggers/action-based-triggers.md)
* [Scheduled Triggers](/docs/concepts/agentic-workflows/agentic-workflow-triggers/scheduled-triggers.md)
* [Agentic Workflow Code Steps](/docs/concepts/agentic-workflows/automation-code-steps.md)

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developer.kizen.com/docs/concepts/agentic-workflows/agentic-workflow-triggers/webhook-triggers.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.