Skip to main content
Available starting with FlowX.AI 5.6.0Incoming Webhooks require the webhook-gateway microservice to be deployed.

​
Overview

Incoming Webhooks allow external systems to trigger FlowX processes by sending HTTP POST requests to a generated URL. Each webhook gets a unique, cryptographically secure API key for authentication — no IMAP setup, no polling, just a direct HTTP call. Use webhooks when you need to:
  • Receive events from third-party platforms (payment processors, CRMs, ERPs) that support outbound webhooks
  • Trigger processes from CI/CD pipelines or internal tools via simple HTTP calls
  • Replace polling-based integrations with event-driven process starts

API key authentication

Each webhook gets a unique, secure API key included in the URL

JSON payload forwarding

Webhook body and HTTP headers are forwarded to the process instance as variables

Manage Triggers UI

Activate, deactivate, and manage webhook URLs from Runtime Settings

Zero configuration

No server settings needed — create the data source, connect to a process, activate

​
How it works

1

Create an Incoming Webhook data source

In Integration Designer, create a new data source and select Incoming Webhook. Provide a name and optional description. No connection settings are required.
2

Connect to a Message Start Event

In your process definition, add a Message Start Event node. Set the Trigger Type to Incoming Webhook and select your webhook data source.
3

Commit and activate

Commit the version, then go to Runtime → Manage Triggers. The webhook appears as Deactivated. Click the action menu and select Activate.
4

Get the webhook URL

From the trigger’s action menu, select Get URL. Copy the generated URL (includes the API key as a query parameter) and configure it in your external system.
5

External system sends POST request

When the external system POSTs JSON to the webhook URL, the webhook-gateway service validates the API key, publishes the event to Kafka, and the process engine starts a new process instance.

​
Creating a webhook data source

1

Navigate to Data Sources

Go to Integrations → Data Sources in your project.
2

Add a new data source

Click + and select Incoming Webhook as the data source type.
3

Configure basic information

FieldRequiredDescription
NameYesA unique name for the webhook (3–50 characters, letters, numbers, [] () . _ -)
DescriptionNoPurpose or context for this webhook
4

Create

Click Create. The webhook data source is ready to be connected to a process.
Incoming Webhook data source page
Incoming Webhooks accept POST requests with JSON payloads (max 1 MB). No connection settings, credentials, or polling configuration is needed.
When deleting a webhook data source, deactivate it first and remove the URL from any third-party systems that use it. Deleting the webhook in FlowX does not notify external systems — they will continue sending requests that return errors.

​
Connecting to a Message Start Event

To use the webhook, connect it to a Message Start Event node in your process definition.
1

Open your process definition

Open the process in the Process Designer.
2

Add a Message Start Event node

Drag a Message Start Event from the Start Events section of the node palette onto the canvas.
3

Configure the Process Trigger

In the node configuration panel, under Process Trigger:
  • Set Trigger Type to Incoming Webhook
  • In Select Webhook, choose your webhook data source from the dropdown
4

Save the node

Click Save to persist the configuration.
Message Start Event configured with Incoming Webhook trigger

​
Managing webhooks at runtime

​
Activating a webhook

For a webhook to appear in Manage Triggers:
  1. The webhook data source must be created
  2. The webhook must be connected to a Message Start Event node
  3. The version must be committed
Navigate to Runtime → Manage Triggers to view and control webhooks:
ColumnDescription
StateActive or Deactivated
Trigger TypeWebhook
Event NameThe webhook data source name
LocationProject and branch information
Use the action menu (three-dot icon) to:
  • Activate — Start accepting webhook requests
  • Deactivate — Stop accepting requests. The API key and URL are preserved, so you can reactivate later without reconfiguring external systems.
  • Get URL — View and copy the webhook URL with API key
A single webhook can trigger multiple processes — add the same webhook data source to Message Start Event nodes in different process definitions. Each incoming request starts all connected processes.
Manage Triggers showing active webhook

​
Webhook URL and API key

When you activate a webhook and select Get URL, a modal displays:
  • Webhook URL — The full URL including the API key as a flowxApiKey query parameter
  • Copy button — Copies the URL to clipboard
  • Reset API Key — Generates a new API key (invalidates the previous URL)
Webhook URL modal with API key and Reset button
URL format: 
https://{services-host}/webhooks/incoming/{orgId}/{workspaceId}/{appId}/{resourceDefinitionId}?flowxApiKey={apiKey}
Resetting the API key creates a new webhook URL. Update the URL in all third-party systems that use it, or they will receive 401 Unauthorized errors.

​
Webhook payload

When an external system POSTs to the webhook URL, the following data is available in the process instance: 
{
  "webhookData": {
    "dateTime": "2026-03-23T15:30:00Z",
    "payload": {
      "orderId": "ORD-12345",
      "status": "completed",
      "amount": 299.99
    },
    "headers": {
      "Content-Type": "application/json",
      "X-Custom-Header": "value"
    }
  }
}
FieldTypeDescription
dateTimestring (ISO 8601)When the webhook was received
payloadobject or stringThe POST request body (parsed as JSON if valid, raw string otherwise)
headersobjectAll HTTP headers from the incoming request
The maximum payload size is 1 MB. Requests exceeding this limit are rejected.

​
Authentication

Webhook authentication uses API keys:
  • Each webhook registration gets a unique 32-byte, base64-URL-encoded API key
  • The key is passed as the flowxApiKey query parameter in the webhook URL
  • Validation uses constant-time comparison to prevent timing attacks
  • Invalid or missing keys return 401 Unauthorized
  • Inactive webhooks return 404 Not Found

​
Error handling

HTTP StatusCauseResolution
200 OKWebhook accepted and published to Kafka—
400 Bad RequestMalformed payload (not valid JSON)Verify the POST body is valid JSON
401 UnauthorizedInvalid or missing API keyCheck the flowxApiKey parameter matches the active webhook URL
404 Not FoundWebhook registration not found or deactivatedVerify the webhook is activated in Manage Triggers
413 Payload Too LargeRequest body exceeds 1 MBReduce the payload size or split into multiple requests
500 Internal Server ErrorProcessing errorCheck webhook-gateway service logs
Failed webhook events appear in Runtime → Failed Triggers with details about the failure cause.

​
Best practices

Use HTTPS

Always use HTTPS URLs in production to protect the API key in transit

Validate payloads in your process

Add validation logic in your process to handle unexpected or malformed payloads gracefully

Monitor Failed Triggers

Regularly check the Failed Triggers section for webhook processing errors

Rotate keys periodically

Use the Reset API Key feature to rotate webhook credentials, then update the URL in external systems

Message Start Event

Configure message-based and webhook process triggers

Email Trigger

Start processes from incoming emails via IMAP

Integration Designer

Build integration workflows and manage data sources

Webhook Gateway setup

Deploy and configure the webhook-gateway microservice
Last modified on March 25, 2026