> 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/webhook-smartconnectors/configuring-webhook-smartconnectors.md).

# Configuring Webhook SmartConnectors

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

**Purpose:** Explains how to create a Webhook <code class="expression">space.vars.smartconnector</code> and complete the three-step configuration wizard to prepare it for production use.
{% endhint %}

## Overview

Webhook <code class="expression">space.vars.smartconnectors</code> receive inbound data from external systems and process it using SQL before loading it into a <code class="expression">space.vars.Kizen\_company\_name</code> <code class="expression">space.vars.object</code>. Each Webhook <code class="expression">space.vars.smartconnector</code> exposes a unique endpoint that accepts incoming payloads, queues them, and processes them on a configurable schedule.

***

## Setting Up Webhook SmartConnectors

{% stepper %}
{% step %}

### Create the SmartConnector

* Navigate to **Data** in the top navigation bar and select **SmartConnectors**.

<div data-with-frame="true"><figure><img src="/files/lihGFx47DkB8pQb2X5WV" alt="" width="375"><figcaption></figcaption></figure></div>

* Click **NEW SMARTCONNECTOR** in the top right corner.

<div data-with-frame="true"><figure><img src="/files/jGzyNzFRTSWKWkKVRPf4" alt="" width="563"><figcaption></figcaption></figure></div>

* In the **Add SmartConnector** dialog, enter a name in the **SmartConnector Name** field.
* Set **Choose Connector Type** to **Webhook**.

<div data-with-frame="true"><figure><img src="/files/sTWjLAvQH7D6p2cztXqM" alt="" width="375"><figcaption></figcaption></figure></div>

* Select the <code class="expression">space.vars.Kizen\_company\_name</code> <code class="expression">space.vars.object</code> this <code class="expression">space.vars.smartconnector</code> will load data into using the **Choose Primary Object** dropdown.
* Click **SAVE**. The <code class="expression">space.vars.smartconnector</code> is created and you land on the Settings tab.
  {% endstep %}

{% step %}

### &#x20;Open the Configuration Wizard

* Click the **Build** tab. This will bring you to the <code class="expression">space.vars.smartconnector</code> canvas.

<div data-with-frame="true"><figure><img src="/files/3g29ethdUwTYSkQlNa5q" alt="" width="563"><figcaption></figcaption></figure></div>

* Click the **Connection Trigger** card on the Build canvas.

<div data-with-frame="true"><figure><img src="/files/I9zbUmZNtLH0kgiCnl7u" alt="" width="563"><figcaption></figcaption></figure></div>

* This opens the three-step configuration wizard: **General Settings**, **Configure Connection**, and **Initialize Variables**.
  {% endstep %}

{% step %}

### General Settings

* The **Webhook URL** is your <code class="expression">space.vars.smartconnector</code>'s unique inbound endpoint, generated automatically. The URL contains a UUID by default. You can substitute the <code class="expression">space.vars.smartconnector</code>'s API Name for the UUID if you need a single endpoint that works across multiple businesses. When using the API Name, the business ID in your authentication credentials determines which business receives the data.

<div data-with-frame="true"><figure><img src="/files/rrrMTLAK4wMbsQELzWhE" alt="" width="563"><figcaption></figcaption></figure></div>

* Set **Process New Webhooks Every** to configure how frequently queued webhooks are batched and processed. The default is **5 Minutes**.
* Optionally add an **Additional Notification Email** or **Additional Error Notification Email**.
* Click **SAVE & CONTINUE.**
  {% endstep %}

{% step %}

### Configure Connection

* Click **GENERATE SAMPLE FILE** to define the webhook payload format and create a sample CSV based on the payload, or drag and drop a file directly into the upload area. Only Webhook CSV files are supported.

<div data-with-frame="true"><figure><img src="/files/EHkiSud5nQo1tdAPWtGY" alt=""><figcaption></figcaption></figure></div>

* The **Enable SQL Processing** toggle is present on this step. For Webhook <code class="expression">space.vars.smartconnectors</code>, SQL processing is required and the SQL editor is always active.
* Use the **Execute SQL to Create Output CSV** editor to write and test your SQL. The editor has three tabs: **Template** (the auto-generated starting script), **Draft** (your working copy), and **Live** (the published version used in production runs). The CHDB runtime version is shown and selectable here.

<div data-with-frame="true"><figure><img src="/files/IZsg8DDvn7RUShTG56cX" alt="" width="563"><figcaption></figcaption></figure></div>

* Click **Test Execution** to validate your SQL against the sample file. Once the test passes, click **Publish Live** to promote the Draft to Live.
* Click **SAVE & CONTINUE**.
  {% endstep %}

{% step %}

### &#x20;Initialize Variables

* Declare the execution variables that will receive values from your SQL output columns. For each variable, set the **Variable Name**, **Data Source (Column Header)**, **Variable Type**, and whether it is **Required**.

<div data-with-frame="true"><figure><img src="/files/NZHmP82xteoZhwnWSPQO" alt="" width="563"><figcaption></figcaption></figure></div>

* Click **AUTODETECT UNMAPPED COLUMNS** to automatically create variables from any SQL output columns not yet mapped.
* Click **SAVE & FINALIZE** when complete.
  {% endstep %}
  {% endstepper %}

You'll be brought back to the the Builder screen.

<div data-with-frame="true"><figure><img src="/files/XzBZlCpRXrdFmFhakIPh" alt="" width="563"><figcaption></figcaption></figure></div>

***

## What's Next?

Continue to [SmartConnector External Data Sources](/docs/concepts/smartconnectors/smartconnector-external-data-sources.md) to learn how to connect to PostgreSQL, MySQL, Amazon S3, and URL/HTTP data sources from within the SQL environment. This is particularly useful when your Webhook <code class="expression">space.vars.smartconnector</code> needs to enrich inbound payload data with reference information from an external system before loading results into <code class="expression">space.vars.Kizen\_company\_name</code>.

<details>

<summary>Related Topics</summary>

* [SmartConnector Data Model](/docs/concepts/smartconnectors/smartconnector-data-model.md)
* [Running a SmartConnector](/docs/concepts/smartconnectors/running-a-smartconnector.md)
* [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/webhook-smartconnectors/configuring-webhook-smartconnectors.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.