Kizen AgenticOS Hackathon in NYC: 4 hour build, $8,000 prize. Apply Now:
Sign up!
Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Configuring Webhook SmartConnectors

Audience: Developers, Solution Architects, and Technical Admins

Purpose: Explains how to create a Webhook SmartConnector and complete the three-step configuration wizard to prepare it for production use.

Overview

Webhook SmartConnectors receive inbound data from external systems and process it using SQL before loading it into a Kizen Object. Each Webhook SmartConnector exposes a unique endpoint that accepts incoming payloads, queues them, and processes them on a configurable schedule.

Setting Up Webhook SmartConnectors

1

Create the SmartConnector

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

  • Click NEW SMARTCONNECTOR in the top right corner.

  • In the Add SmartConnector dialog, enter a name in the SmartConnector Name field.

  • Set Choose Connector Type to Webhook.

  • Select the Kizen Object this SmartConnector will load data into using the Choose Primary Object dropdown.

  • Click SAVE. The SmartConnector is created and you land on the Settings tab.

2

Open the Configuration Wizard

  • Click the Build tab. This will bring you to the SmartConnector canvas.

  • Click the Connection Trigger card on the Build canvas.

  • This opens the three-step configuration wizard: General Settings, Configure Connection, and Initialize Variables.

3

General Settings

  • The Webhook URL is your SmartConnector's unique inbound endpoint, generated automatically. The URL contains a UUID by default. You can substitute the SmartConnector'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.

  • 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.

4

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.

  • The Enable SQL Processing toggle is present on this step. For Webhook SmartConnectors, 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.

  • 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.

5

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.

  • Click AUTODETECT UNMAPPED COLUMNS to automatically create variables from any SQL output columns not yet mapped.

  • Click SAVE & FINALIZE when complete.

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

What's Next?

Continue to SmartConnector External Data Sources 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 SmartConnector needs to enrich inbound payload data with reference information from an external system before loading results into Kizen.

Related Topics
PreviousWebhook SmartConnectorsNextSmartConnector Design Best Practices

Last updated

Was this helpful?