Incoming Webhook Step

The Incoming Webhook step is a trigger—it must be the first step in a workflow and it starts a new execution each time an external system sends an HTTP request to the generated endpoint. Use it to integrate with third-party systems that push data rather than respond to API calls.

When you create the project, a unique webhookSessionStartUrl is returned in the __meta object of the API response. That is the URL your external system should call to start a session.

Setting up field extraction

To make payload fields available for mapping in later steps:

Enable Listening mode on the step.
Send a sample POST request to the test URL with your expected payload.
Streamline captures the request and extracts the fields.
Save the step — listening mode resets to false, and the extracted fields are stored in mappableFields.

The captured fields can then be referenced in later steps using the step's description as the mapping source (e.g. {{Incoming webhook.body.orderId}}).

Configuration

name	type	required	description
`method`	string	yes	HTTP method to accept: `GET` or `POST`.
`listeningModeEnabled`	boolean	yes	Design-time toggle. Set to `true` to capture a sample request and extract fields. Resets to `false` after fields are extracted. Default: `false`.
`requestPayload`	string	yes	The full captured request (body, query, and headers) stored after a sample request is received. Default: empty string.
`mappableFields`	array	yes	Fields extracted from the captured payload, available for mapping in later steps. Default: empty array.

Mappable fields

Each entry in mappableFields describes a field from the incoming request that becomes available for mapping. Field keys are prefixed with body., query., or headers. depending on where they appear in the request.

name	type	required	description
`key`	string	yes	The field path in the captured request (e.g. `body.orderId`).
`label`	string	yes	Human-readable label for the field (used in the UI).
`type`	string	yes	Data type of the field (e.g. `string`, `number`, `datetime`).
`exampleValue`	string	no	Example value for documentation and design-time testing.

Examples

Let's start with an unconfigured webhook trigger—no fields extracted yet.

{
  "method": "POST",
  "listeningModeEnabled": false,
  "requestPayload": "",
  "mappableFields": []
}

Here's what the step looks like after sending a sample payload and extracting fields. Notice that listeningModeEnabled is back to false and the fields use body. prefixed keys.

{
  "method": "POST",
  "listeningModeEnabled": false,
  "requestPayload": "{\"body\":{\"orderId\":\"ord-789\",\"customerEmail\":\"[email protected]\",\"amount\":149.99,\"status\":\"placed\"},\"query\":{},\"headers\":{}}",
  "mappableFields": [
    { "key": "body.orderId", "type": "string", "label": "Order ID" },
    { "key": "body.customerEmail", "type": "string", "label": "Customer Email" },
    { "key": "body.amount", "type": "number", "label": "Amount" },
    { "key": "body.status", "type": "string", "label": "Status" }
  ]
}