Configuring a webhook trigger

A webhook trigger is the entry point of a workflow that starts from an inbound HTTP call. You declare a path and a method on the trigger node. When you activate the workflow, Flowker serves that path and runs the workflow on every call it accepts. The trigger’s input_contract decides which payloads Flowker accepts and how it decodes them. Choose it before you write the node: it is required, and it fixes the payload format for the whole route.

Before you start

A workflow in draft status. An active workflow is locked, so add the trigger before you activate it. See Getting started with Flowker for the create-and-activate path.
The execute permission on the webhooks resource for every system you let call the path. See Securing a webhook.
For the xsd contract: an XSD document in the registry. Upload it with Upload an XSD schema and keep the id it returns. Your deployment also needs the XML validation service the contract validates through — see XSD_VALIDATOR_URL.
For the openapi contract: an OpenAPI document in the registry (Upload an OpenAPI schema, covered end to end in Connecting your own API). You also need the path and the method of the operation whose request body describes your payload. Derive an operation schema shows you that request body.

Step 1: Read the trigger contract from the catalog

Triggers are built in. You discover them in the catalog, and you never create one.

List the built-in triggers

List catalog triggers returns each trigger with its id, name and version. The webhook trigger’s id is webhook.

curl -s http://localhost:4021/v1/catalog/triggers | jq .

Read the webhook trigger's schema

Get a catalog trigger returns the same fields plus schema — the JSON Schema Flowker validates your trigger node against. Read it when you want the field list from the running instance.

curl -s http://localhost:4021/v1/catalog/triggers/webhook | jq -r '.schema' | jq .

Step 2: Choose the input contract

Mode	What the route accepts	What Flowker does with the payload	Fields the mode requires
`open`	JSON or XML, as you declare in `format`	Decodes the body and runs no contract validation.	`format` — `"json"` or `"xml"`
`xsd`	XML	Validates the document against the XSD schema you referenced.	`xsd_schema_id`
`openapi`	JSON	Validates the payload against exactly one operation of the OpenAPI document you referenced, and rejects a payload that does not conform.	`openapi_schema_id`, `operation_path`, `operation_method`

The mode fixes the route’s payload format. An xsd route is XML and an openapi route is JSON. An open route uses the format you declare, and format belongs to that mode only. Choose open when the caller’s payload has no published contract, or when you want the workflow itself to decide what is acceptable. Choose xsd when a partner sends XML that an XSD document defines. Choose openapi when a partner sends JSON and you hold the OpenAPI document that describes it.

An openapi route never accepts an unchecked payload: when Flowker cannot reach a verdict, it rejects the call with FLK-0720, and the workflow never sees that payload. An xsd route reaches its verdict through the XML validation service your deployment configures — a document that does not conform is rejected with XML_VALIDATION_FAILED, and a verdict Flowker cannot trust with FLK-0720. Configure that service before you put an xsd route in front of a caller.

Step 3: Decide how the webhook answers

`response_mode`	What the caller receives
`async` (default)	HTTP `202` with the execution receipt, as soon as the execution starts. The workflow continues in the background, and the caller reads the outcome from Get execution results.
`sync`	Flowker holds the connection until the execution reaches a terminal state, for up to 15 seconds, then returns the outcome. If the window closes first, the caller receives the same `202` receipt plus a `Location` header pointing at the results endpoint.

On a sync route, response_view shapes the body:

`response_view`	Body
`full` (default)	The complete execution envelope: `executionId`, `workflowId`, `status`, `stepResults` and `finalOutput`.
`final_output`	Only the execution’s final business output.
`receipt`	The lean receipt: `executionId`, `workflowId`, `status` and `startedAt`.
`passthrough`	The shape the terminal step implies — a relayed provider response, or a terminal `set_output` node’s own output.

response_view is inert on an async route. For the full passthrough rules and for the responseStatusCode override, see Synchronous response mode.

Pick async when the caller only needs to know the event arrived. Pick sync when the caller needs the answer in the same call — a partner that expects a decision on the same connection, for example.

Step 4: Write the trigger node

The webhook trigger is a node with type: "trigger" and these fields in its data:

Field	When you set it	Value
`triggerType`	Always	`"webhook"`.
`path`	Always	The path to serve, such as `"payments/received"`. It carries as many segments as you need.
`method`	Always	The method the route answers: `GET`, `POST`, `PUT`, `PATCH` or `DELETE`, in upper case.
`input_contract`	Always	`"open"`, `"xsd"` or `"openapi"`.
`format`	With `open`	`"json"` or `"xml"`.
`xsd_schema_id`	With `xsd`	The id Upload an XSD schema returned.
`openapi_schema_id`	With `openapi`	The id Upload an OpenAPI schema returned.
`operation_path`	With `openapi`	The operation path as the OpenAPI document writes it, such as `"/orders"`. Flowker matches it exactly.
`operation_method`	With `openapi`	The operation’s method: `GET`, `POST`, `PUT`, `PATCH` or `DELETE`.
`response_mode`	Optional	`"async"` (default) or `"sync"`.
`response_view`	Optional	`"full"` (default), `"final_output"`, `"receipt"` or `"passthrough"`.

The trigger configuration is a closed contract. Saving a workflow whose webhook trigger omits path, method or input_contract, misses a field its input_contract mode requires, names another mode’s schema id or operation field, or carries a key or a value the schema does not accept fails with FLK-0934.

{
  "id": "trigger-1",
  "type": "trigger",
  "name": "Payment received",
  "position": { "x": 0, "y": 0 },
  "data": {
    "triggerType": "webhook",
    "path": "payments/received",
    "method": "POST",
    "input_contract": "open",
    "format": "json"
  }
}

{
  "id": "trigger-1",
  "type": "trigger",
  "name": "Statement received",
  "position": { "x": 0, "y": 0 },
  "data": {
    "triggerType": "webhook",
    "path": "statements/received",
    "method": "POST",
    "input_contract": "open",
    "format": "xml"
  }
}

{
  "id": "trigger-1",
  "type": "trigger",
  "name": "STR0008 received",
  "position": { "x": 0, "y": 0 },
  "data": {
    "triggerType": "webhook",
    "path": "spb/str0008",
    "method": "POST",
    "input_contract": "xsd",
    "xsd_schema_id": "0f9a1c3e-5b7d-4c2a-9e18-6d4b2f7a1c05"
  }
}

{
  "id": "trigger-1",
  "type": "trigger",
  "name": "Order paid",
  "position": { "x": 0, "y": 0 },
  "data": {
    "triggerType": "webhook",
    "path": "orders/paid",
    "method": "POST",
    "input_contract": "openapi",
    "openapi_schema_id": "3c7e9b21-84af-4d6c-b0f1-2a5c8e93d7b4",
    "operation_path": "/orders",
    "operation_method": "POST"
  }
}

{
  "id": "trigger-1",
  "type": "trigger",
  "name": "Authorize payment",
  "position": { "x": 0, "y": 0 },
  "data": {
    "triggerType": "webhook",
    "path": "payments/authorize",
    "method": "POST",
    "input_contract": "open",
    "format": "json",
    "response_mode": "sync",
    "response_view": "passthrough"
  }
}

Flowker registers the path with a leading slash and without a trailing one, so payments/received, /payments/received and payments/received/ all register the same route.

Step 5: Activate the workflow

Create the workflow

Send the node with the rest of your workflow to Create a workflow. The workflow lands in draft status, and Flowker validates the trigger configuration here — a contract error answers FLK-0934.

Activate it

Call Activate a workflow. Activation registers the path and the method. It also resolves what the contract references. A missing XSD schema answers FLK-0930 and a missing OpenAPI schema FLK-0931. An operation the document does not declare answers FLK-0932, and an operation with no request body answers FLK-0933.

curl -s -X POST http://localhost:4021/v1/workflows/019c96a0-0ac0-7de9-9f53-9cf842a2ee5a/activate | jq .

One active workflow owns a path and method pair within your tenant. Activating a second workflow on the same pair answers FLK-0360. Deactivating a workflow releases its routes, so you can hand a path to a new version.

Step 6: Call the route and confirm it works

Send the call the way your caller will:

curl -i -X POST http://localhost:4021/v1/webhooks/payments/received \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7f3e1a2b-4c5d-6e7f-8a9b-0c1d2e3f4a5b" \
  -d '{ "transactionId": "txn-123", "amount": 1500.00 }'

An async route answers 202 with the receipt:

{
  "executionId": "019c96a0-10ce-75fc-a273-dc799079a99c",
  "workflowId": "019c96a0-0ac0-7de9-9f53-9cf842a2ee5a",
  "status": "running",
  "startedAt": "2026-03-18T14:35:00Z"
}

A sync route answers with the execution’s outcome, in the shape its response_view selects. The status it carries depends on the view and on how the execution ended — Synchronous response mode holds those rules. Three signals tell you the route worked:

A response that started an execution carries X-Webhook-Workflow-ID and X-Webhook-Execution-ID, so you can tie a call to the workflow it reached and the execution it started.
Get execution results reports the step results and the final output for that executionId.
The execution’s input carries a _webhook object with the method, the path and the caller’s address. Use it to confirm the workflow saw the call it should. See Webhook metadata.

A repeat delivery that carries the same Idempotency-Key returns the original execution instead of starting a second one, and its body carries idempotencyReplayed: true with the original status. Send a new key to run the workflow again. The five verbs each have their own reference page: POST, GET, PUT, PATCH and DELETE.

When a call fails

Code	When it happens	What to do
`FLK-0934`	You save the workflow.	Compare the trigger `data` against the field table in Step 4. Check this code first when a webhook trigger does not save.
`FLK-0930` … `FLK-0933`	You activate the workflow.	Confirm the schema id, and for `openapi` confirm the operation path and method exist in the document and that the operation declares a request body.
`FLK-0360`	You activate the workflow.	Another active workflow owns that path and method. Choose another path, or deactivate the other workflow.
`FLK-0361`	The caller sends a request.	No route answers that path and method. Confirm the workflow is active, and that the caller uses the method the trigger declares.
`FLK-0501`	The caller sends a request.	The workflow resolved but is not active. Activate it.
`FLK-0001`	The caller sends a request.	The body of a JSON route is not valid JSON.
`FLK-0364`	The caller sends a request.	The body of an XML route is not well-formed XML. An XML route reports it as `XML_MALFORMED` in the `<error>` document.
`XML_VALIDATION_FAILED`	The caller sends a request.	The body of an `xsd` route is well-formed XML but does not conform to the XSD document. The `<error>` document names the failing line and column.
`FLK-0935`	The caller sends a request.	The JSON body of an `openapi` route does not conform to the pinned operation’s request body. The message names the failing field.
`FLK-0720`	The caller sends a request.	Flowker could not validate the payload, so it rejected the call. Confirm the validation service and the referenced schema are available to your deployment.
`FLK-0363`	The caller sends a request.	The body is over 1 MB. Send less in one call.

A JSON route returns code, title and message. An XML route returns an <error> document. See the Flowker error list for every code and both shapes.

What’s next

Integration guide

Connect the workflow to external services, and read the full synchronous-response rules.

Workflow design guide

Build the rest of the graph the trigger enters.

Overview

Guides

Console

Operations

Configuring a webhook trigger

Before you start

Step 1: Read the trigger contract from the catalog

Step 2: Choose the input contract

Step 3: Decide how the webhook answers

Step 4: Write the trigger node

Step 5: Activate the workflow

Step 6: Call the route and confirm it works

When a call fails

What’s next

Integration guide

Workflow design guide

​Before you start

​Step 1: Read the trigger contract from the catalog

​Step 2: Choose the input contract

​Step 3: Decide how the webhook answers

​Step 4: Write the trigger node

​Step 5: Activate the workflow

​Step 6: Call the route and confirm it works

​When a call fails

​What’s next

Integration guide

Workflow design guide

Before you start

Step 1: Read the trigger contract from the catalog

Step 2: Choose the input contract

Step 3: Decide how the webhook answers

Step 4: Write the trigger node

Step 5: Activate the workflow

Step 6: Call the route and confirm it works

When a call fails

What’s next