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.

SmartConnector Webhook Trigger API

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.

Overview

The SmartConnector Webhook Trigger API delivers inbound data to a Webhook SmartConnector's endpoint for batched processing. Unlike the Start SmartConnector Flow API, which triggers an immediate run, the SmartConnector Webhook Trigger API queues incoming payloads and processes them in batches on the SmartConnector'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 SmartConnector for batched processing on the SmartConnector's configured schedule.

  • Replace individual Record-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 Records rather than once per Record.

  • Integrate a third-party system that supports outbound webhooks with a Kizen SmartConnector workflow - any external system that can send an HTTP POST can deliver data to a Webhook SmartConnector through this endpoint.

SmartConnector Webhook Trigger API Behavior

Use this endpoint to deliver inbound webhook payloads to a Webhook SmartConnector 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 SmartConnector's configured cadence, not at the time of receipt

  • Holds queued payloads while the SmartConnector is inactive - they are processed when the SmartConnector is activated

  • Requires SQL processing to be enabled - Webhook SmartConnectors always have SQL enabled

Processing Runs On Time-Windowed Schedule

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.

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 SmartConnector:

  • 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 SmartConnector has a status of inactive, payloads continue to accumulate in the queue but are not processed until the SmartConnector is activated. In production, be aware that a backlog of queued payloads will all be processed when the SmartConnector is re-activated. This behavior can be useful during development because you can queue payloads while the SmartConnector is inactive and validate the full flow once you activate it.

For more information, check out Webhook SmartConnector.

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 SmartConnector's SQL script to process correctly.

SmartConnector Identifier

Both UUID and API Name are accepted as the SmartConnector identifier. The API Name is recommended for stability across environments, as it does not change when a SmartConnector 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.

For more information, see Authentication.

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 SmartConnector 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 SmartConnector that has zero concurrent executions configured

SmartConnector Webhook Trigger Endpoint

Want to try the API out? Visit our Swagger docs.

Send webhook data

post

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.

Authorizations
X-API-KEYstringRequired
X-BUSINESS-IDstringRequired
X-USER-IDstringRequired
Path parameters
connector_identifierstringRequired
Query parameters
example_paramstringOptional

Example query parameter. Any query parameter is accepted.

Body
Other propertiesanyOptional
Responses
201

Webhook accepted and queued for asynchronous processing. The response body is empty.

No content
post/api/smart-connectors/{connector_identifier}/webhook
POST /api/smart-connectors/{connector_identifier}/webhook HTTP/1.1
X-API-KEY: YOUR_API_KEY
X-BUSINESS-ID: YOUR_BUSINESS_ID
X-USER-ID: YOUR_USER_ID
Content-Type: application/json
Accept: */*
Content-Length: 58

{
  "key1": {
    "nested_key": "nested_value"
  },
  "key2": "key2_value"
}
No content

SmartConnector Webhook Trigger Schemas

What's Next?

Continue to SmartConnector Permissions to understand how permissions govern access to SmartConnectors at both the configuration level and at runtime. SmartConnector Permissions covers who can view, edit, activate, and run a SmartConnector, and explains how runtime execution behavior differs from Agentic Workflows in ways that matter when designing SmartConnectors that write to sensitive fields.

Related Topics
PreviousStart SmartConnector Flow APINextSmartConnector Permissions

Last updated

Was this helpful?