> 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/smartconnectors/smartconnector-apis/smartconnector-webhook-trigger-api.md).

# SmartConnector Webhook Trigger API

{% hint style="success" %}
**Audience**: Developers and Integrators

**Purpose:** Enables developers to deliver inbound webhook payloads to a Webhook SmartConnector for batched processing, covering the queuing model, payload format options, size limits, and how to verify that a queued payload was processed.
{% endhint %}

## Overview

The **SmartConnector Webhook Trigger** API delivers inbound data to a Webhook <code class="expression">space.vars.smartconnector</code>'s endpoint for batched processing. Unlike the Start SmartConnector Flow API, which triggers an immediate run, the <code class="expression">space.vars.smartconnector</code> Webhook Trigger API queues incoming payloads and processes them in batches on the <code class="expression">space.vars.smartconnector</code>'s configured cadence.

### Why Use This API?

You can use the **SmartConnector Webhook Trigger** API when you need to:

* Deliver webhook payloads from an external system to a Webhook <code class="expression">space.vars.smartconnector</code> for batched processing on the <code class="expression">space.vars.smartconnector</code>'s configured schedule.
* Replace individual <code class="expression">space.vars.entity</code>-level webhook processing with a batched approach for high-volume or transformation-heavy use cases where SQL processing and load step logic should run once across many <code class="expression">space.vars.entities</code> rather than once per <code class="expression">space.vars.entity</code>.
* Integrate a third-party system that supports outbound webhooks with a Kizen <code class="expression">space.vars.smartconnector</code> workflow - any external system that can send an HTTP POST can deliver data to a Webhook <code class="expression">space.vars.smartconnector</code> through this endpoint.

***

## SmartConnector Webhook Trigger API Behavior

Use this endpoint to deliver inbound webhook payloads to a Webhook <code class="expression">space.vars.smartconnector</code> for queued batch processing. It:

* Accepts any supported content type as the request body - JSON is recommended but not required; an empty JSON body ({}) is valid
* Queues the payload immediately and returns HTTP 201 to confirm receipt - processing happens on the <code class="expression">space.vars.smartconnector</code>'s configured cadence, not at the time of receipt
* Holds queued payloads while the <code class="expression">space.vars.smartconnector</code> is inactive - they are processed when the SmartConnector is activated
* Requires SQL processing to be enabled - Webhook SmartConnectors always have SQL enabled

### **Proce**ssing Runs On Time-Windowed Schedule&#x20;

Payloads are not processed a fixed amount of time after they arrive. Instead, the system groups payloads into fixed time windows based on the SmartConnector's configured cadence.&#x20;

For example, if the cadence is set to 15 minutes, payloads are processed at fixed points in the hour - such as 2:00, 2:15, 2:30 - not 15 minutes after each individual payload arrives. A payload received at 2:07 PM will be processed at the 2:15 PM window, not at 2:22 PM. Plan your integration around this behavior.

### **Cadence Options**

The following processing cadence values are available when configuring a Webhook <code class="expression">space.vars.smartconnector</code>:

* 30 seconds
* 60 seconds
* 5 minutes (300 seconds)
* 15 minutes (900 seconds)
* 30 minutes (1800 seconds)
* 60 minutes (3600 seconds)
* 3 hours (10800 seconds)

### **Queued Payloads**

If the <code class="expression">space.vars.smartconnector</code> has a status of inactive, payloads continue to accumulate in the queue but are not processed until the <code class="expression">space.vars.smartconnector</code> is activated. In production, be aware that a backlog of queued payloads will all be processed when the <code class="expression">space.vars.smartconnector</code> is re-activated. This behavior can be useful during development because you can queue payloads while the <code class="expression">space.vars.smartconnector</code> is inactive and validate the full flow once you activate it.&#x20;

For more information, check out [Webhook SmartConnector](/docs/concepts/smartconnectors/webhook-smartconnectors.md).

#### **Payload Size Limits**

The request body must not exceed 256 KB. Query string parameters must not exceed approximately 4 KB.

#### **Accepted Payload Formats**

The endpoint accepts the following content types:

* `application/json` (recommended - no required structure; an empty object is valid)
* `application/x-www-form-urlencoded`
* `multipart/form-data`
* `application/xml`
* `text/html`
* `text/csv`

Non-JSON formats are accepted but may require additional parsing logic in the <code class="expression">space.vars.smartconnector</code>'s SQL script to process correctly.

### SmartConnector Identifier

Both UUID and API Name are accepted as the <code class="expression">space.vars.smartconnector</code> identifier. The API Name is recommended for stability across environments, as it does not change when a <code class="expression">space.vars.smartconnector</code> is re-created or migrated.

### Authentication

Webhook requests must include the standard Kizen API authentication headers: `X-API-KEY`, `X-BUSINESS-ID`, and `X-USER-ID`. Requests without valid business context will be rejected.&#x20;

For more information, see [Authentication](/docs/developers/authentication.md).&#x20;

### Verifying Payload Was Processed

Because the Webhook Trigger API returns no execution ID, you cannot poll for a queued payload's status the way you would with the **Start SmartConnector Flow** API. Instead, configure the `execution_ended_webhook_url` field in <code class="expression">space.vars.smartconnector</code> Settings to receive an event-driven notification when each batch run completes.

### **Error Conditions**

The following conditions will return an error response:

* An invalid connector identifier
* A payload exceeding the 256 KB body size limit
* Missing or invalid authentication headers
* Sending a payload to an inactive <code class="expression">space.vars.smartconnector</code> that has zero concurrent executions configured&#x20;

***

## SmartConnector Webhook Trigger Endpoint

Want to try the API out? Visit our [Swagger docs](https://app.go.kizen.com/api/docs/public/swagger#/smart-connectors/smart_connectors_webhook_create).

## Send webhook data

> Send inbound webhook data to a Webhook SmartConnector's endpoint. The request body and query string are accepted as-is and queued for asynchronous processing; the connector run is created in the background. The response is returned immediately with an empty body and does not include an execution ID. Only connectors of type webhook accept requests at this endpoint, and the request body is limited to 250 KB and must be UTF-8 encoded.

```json
{"openapi":"3.0.3","info":{"title":"Kizen API","version":"1.0.0"},"security":[{"businessId":[],"userId":[],"apiKey":[]}],"components":{"securitySchemes":{"businessId":{"type":"apiKey","in":"header","name":"X-BUSINESS-ID"}},"schemas":{"SmartConnectorWebhookErrorResponse":{"type":"object","properties":{"detail":{"type":"string"}},"required":["detail"]}}},"paths":{"/api/smart-connectors/{connector_identifier}/webhook":{"post":{"operationId":"smart_connectors_webhook_create","description":"Send inbound webhook data to a Webhook SmartConnector's endpoint. The request body and query string are accepted as-is and queued for asynchronous processing; the connector run is created in the background. The response is returned immediately with an empty body and does not include an execution ID. Only connectors of type webhook accept requests at this endpoint, and the request body is limited to 250 KB and must be UTF-8 encoded.","summary":"Send webhook data","parameters":[{"in":"path","name":"connector_identifier","schema":{"type":"string"},"required":true},{"in":"query","name":"example_param","schema":{"type":"string"},"description":"Example query parameter. Any query parameter is accepted."}],"tags":["smart-connectors"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","additionalProperties":{}}},"application/x-www-form-urlencoded":{"schema":{"type":"object","additionalProperties":{}}},"multipart/form-data":{"schema":{"type":"object","additionalProperties":{}}},"application/xml":{"schema":{"type":"object","additionalProperties":{}}},"text/html":{"schema":{"type":"object","additionalProperties":{}}},"text/csv":{"schema":{"type":"object","additionalProperties":{}}}}},"responses":{"201":{"description":"Webhook accepted and queued for asynchronous processing. The response body is empty."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SmartConnectorWebhookErrorResponse"}}},"description":"The request was rejected. Returned when the SmartConnector is not of type webhook, the request body exceeds the 250 KB limit, or the request body is not UTF-8 encoded."}}}}}}
```

### SmartConnector Webhook Trigger Schemas

## The SmartConnectorWebhookErrorResponse object

```json
{"openapi":"3.0.3","info":{"title":"Kizen API","version":"1.0.0"},"components":{"schemas":{"SmartConnectorWebhookErrorResponse":{"type":"object","properties":{"detail":{"type":"string"}},"required":["detail"]}}}}
```

***

## What's Next?

Continue to [SmartConnector Permissions](/docs/concepts/smartconnectors/smartconnector-permissions.md) to understand how permissions govern access to <code class="expression">space.vars.smartconnectors</code> at both the configuration level and at runtime. <code class="expression">space.vars.smartconnector</code> Permissions covers who can view, edit, activate, and run a <code class="expression">space.vars.smartconnector</code>, and explains how runtime execution behavior differs from <code class="expression">space.vars.automations</code> in ways that matter when designing <code class="expression">space.vars.smartconnectors</code> that write to sensitive fields.

<details>

<summary>Related Topics</summary>

* [SmartConnector APIs](/docs/concepts/smartconnectors/smartconnector-apis.md)
* [Running a SmartConnector](/docs/concepts/smartconnectors/running-a-smartconnector.md)
* Building with SmartConnectors **(Topic Coming Soon)**
* [SmartConnector Permissions](/docs/concepts/smartconnectors/smartconnector-permissions.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/smartconnectors/smartconnector-apis/smartconnector-webhook-trigger-api.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.