> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.
# Integration guide
> Connect external services to Flowker using executors. Configure authentication, test connectivity, and run workflows with real integrations.
Flowker connects to external services (such as fraud engines, payment processors, KYC providers, and more) through executor configurations.
In this guide, you will explore the catalog, create and configure an executor, test connectivity, use it in a workflow, and understand Flowker's resilience model.
## Executor configuration lifecycle
***
Before an executor can be used in a workflow, it moves through the following lifecycle:
Executor configurations are managed through the `/v1/executors` endpoints (list, get, update, delete). The lifecycle states (`unconfigured`, `configured`, `tested`, `active`, `disabled`) are tracked internally — transitions happen through the service layer.
| Status | What it means | Next step |
| -------------- | ----------------------------------------------------- | -------------------- |
| `unconfigured` | Created with connection details but not fully set up. | Configure it (PATCH) |
| `configured` | Connection details defined and validated. | Test connectivity |
| `tested` | Connectivity test passed. | Activate it |
| `active` | Available for workflow execution. | — |
| `disabled` | Temporarily out of service. | Enable it |
The executor configuration lifecycle is managed through the service layer (`MarkConfigured`, `MarkTested`, `Activate`, `Disable`, `Enable` commands). Note that the current HTTP API exposes `GET`, `PATCH`, and `DELETE` endpoints. `PATCH` updates configuration data but does not trigger status transitions.
## Step 1: Explore the catalog
***
Before creating an executor configuration, browse the catalog to see what's already available.
The catalog is a read-only registry of built-in executors and triggers that ship with Flowker. You don't need to create catalog entries — you discover them and then configure the ones you need.
Call the [List catalog executors](/en/reference/flowker/list-catalog-executors) endpoint to see all executor types Flowker supports out of the box — HTTP requests, data transformations, and more.
Call the [List catalog triggers](/en/reference/flowker/list-catalog-triggers) endpoint to see how workflows can be started — webhooks or manual API calls.
Identify the executor type and trigger type that match your integration. You'll reference these when creating your configuration in the next step.
Think of the catalog as a menu: it shows what Flowker can connect to. Executor configurations are your specific orders — the credentials, URLs, and settings for each service you want to use.
## Step 2: Configure a provider connection and executor
***
Executors are built-in components that ship with Flowker. You do not create them via the API — they are discovered through the catalog ([`GET /v1/catalog/executors`](/en/reference/flowker/list-catalog-executors)) in [Step 1](#step-1-explore-the-catalog).
To use an executor, you first create a **provider configuration** that defines the connection to the external service, and then manage **executor configurations** that bind a catalog executor to a provider connection with operation-specific settings.
### Create a provider configuration
Call [`POST /v1/provider-configurations`](/en/reference/flowker/create-provider-configuration) to set up the connection to your external service — including the base URL, credentials, and environment-specific settings. The `config` field is validated against the provider's JSON Schema from the catalog.
See [Provider configurations](#provider-configurations) below for details and examples.
### Manage executor configurations
Once you have a provider configuration, manage executor configurations through the `/v1/executors` endpoints:
| Operation | Endpoint |
| --------- | ---------------------------------------------------------------------------------- |
| List | [`GET /v1/executors`](/en/reference/flowker/list-executor-configurations) |
| Get | [`GET /v1/executors/{id}`](/en/reference/flowker/get-executor-configuration) |
| Update | [`PATCH /v1/executors/{id}`](/en/reference/flowker/update-executor-configuration) |
| Delete | [`DELETE /v1/executors/{id}`](/en/reference/flowker/delete-executor-configuration) |
An executor configuration defines which endpoint to call and how to map data for that operation. It references a provider configuration for the actual connection details.
See the [Executor configurations API](/en/reference/flowker/list-executor-configurations) for the full API reference.
## Authentication types
***
Flowker supports multiple authentication methods.
Use the method required by your external service.
| Type | Description | Config fields |
| ------------------------- | -------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| `none` | No authentication. | — |
| `api_key` | API key in header or query. | `key`, `header_name`, `location`, `query_param_name`, `prefix` |
| `bearer` | Bearer token in Authorization header. | `token` |
| `basic` | Username and password (Base64). | `username`, `password` |
| `oidc_client_credentials` | OAuth 2.0 client credentials flow with automatic token management. | `issuer_url`, `client_id`, `client_secret`, `scopes` |
| `oidc_user` | OAuth 2.0 resource owner password flow. | `issuer_url`, `client_id`, `username`, `password`, `client_secret`, `scopes` |
| `oauth2_token_endpoint` | OAuth 2.0 client credentials against a token endpoint (no OIDC discovery). | `token_url`, `client_id`, `client_secret`, `scopes` |
For OAuth 2.0 integrations, use `oidc_client_credentials`. Flowker handles token acquisition and renewal automatically.
```json theme={null}
{
"authentication": {
"type": "oidc_client_credentials",
"config": {
"issuer_url": "https://auth.fraudshield.com/realms/fraudshield",
"client_id": "flowker-integration",
"client_secret": "secret-value",
"scopes": ["transactions:read", "transactions:score"]
}
}
}
```
## Provider configurations
***
Provider configurations are separate from executor configurations. While an executor configuration defines how Flowker calls a specific operation on an external service, a provider configuration represents a configured connection to a provider instance — including its base URL, credentials, and environment-specific settings.
Think of it this way: a provider configuration is the *connection*, and an executor configuration is the *operation* you run over that connection.
### Creating a provider configuration
Create a provider configuration by calling the [Create provider configuration](/en/reference/flowker/create-provider-configuration) endpoint. Provide the `providerId` from the catalog and the provider-specific configuration (base URL, credentials, and so on).
The `config` field is validated against the provider's JSON Schema from the catalog. If it doesn't match, the request returns a `422` error.
```json theme={null}
POST /v1/provider-configurations
{
"name": "Midaz Production",
"description": "Production Midaz instance for balance operations",
"providerId": "midaz",
"config": {
"base_url": "https://midaz.example.com/api/v1",
"api_key": "sk-prod-xxx"
},
"metadata": {
"environment": "production"
}
}
```
### Testing connectivity
After creating a provider configuration, test it with the [Test provider configuration](/en/reference/flowker/test-provider-configuration) endpoint. The test runs three stages — connectivity, authentication, and end-to-end — and returns results for each.
### Enabling and disabling
Provider configurations are created in `active` status. You can temporarily disable one with the [Disable provider configuration](/en/reference/flowker/disable-provider-configuration) endpoint and re-enable it later with the [Enable provider configuration](/en/reference/flowker/enable-provider-configuration) endpoint.
See the [Provider configurations API](/en/reference/flowker/list-provider-configurations) for the full reference.
## Step 3: Configure the executor
***
Mark the executor as configured by calling the [Update executor configuration](/en/reference/flowker/update-executor-configuration) endpoint. This transitions the status from `unconfigured` to `configured`.
## Step 4: Validate your configuration
***
Before using an executor in a workflow, validate its configuration against the catalog schema using the [Validate executor config](/en/reference/flowker/validate-executor-config) endpoint (`POST /v1/catalog/executors/{id}/validate`).
This performs **JSON Schema validation only** — it checks that your configuration object matches the structure the executor expects (required fields, types, formats). It does not test connectivity to the external service.
To test actual connectivity to an external service, use the [Test provider configuration](/en/reference/flowker/test-provider-configuration) endpoint on the provider configuration instead. That endpoint runs connectivity, authentication, and end-to-end checks against the real service.
## Field mapping and data transformation
***
When workflow data doesn't match the format an external service expects — or when a service returns data in a shape the next step can't consume — use field mappings and transformations to bridge the gap.
Field mappings and transformations are defined inside the `data` object of executor nodes. Flowker applies input mappings before calling the external service, and output mappings after receiving the response.
```json theme={null}
{
"id": "executor-balance",
"type": "executor",
"name": "Check Balance",
"data": {
"providerConfigId": "a1b2c3d4-e5f6-4789-a012-345678901234",
"inputMapping": [
{ "source": "workflow.customerId", "target": "executor.accountId" },
{ "source": "workflow.amount", "target": "executor.minimumBalance" }
],
"outputMapping": [
{ "source": "executor.currentBalance", "target": "workflow.balance" },
{ "source": "executor.accountStatus", "target": "workflow.status" }
]
}
}
```
For complex integrations, you can also attach transformations to individual mapping entries (e.g., stripping characters, adding prefixes, changing case) and define Kazaam operations for advanced JSON-to-JSON transformations.
See the [Field mapping reference](/en/flowker/field-mapping-reference) for the complete list of transformation types, JSON structures, and troubleshooting guidance.
## Step 5: Use the executor in a workflow
***
Once your executor configuration is validated, reference it in a workflow. The executor becomes active when it's used in an active workflow.
To temporarily take an executor out of service, update its configuration using the [Update executor configuration](/en/reference/flowker/update-executor-configuration) endpoint.
## Using an executor in a workflow
***
Reference the executor in a workflow node of type `executor`.
The example below creates a payment validation workflow. When a payment arrives, Flowker calls the fraud check executor, evaluates the risk score, and either approves or rejects the payment based on the result.
The workflow has five nodes: a webhook **trigger** that receives the payment, an **executor** node that calls the fraud check service, a **conditional** node that evaluates the score, and two **action** nodes for the approve and reject outcomes. Edges connect them in sequence, with the conditional node branching to either path based on the score threshold.
Use the [Create workflow](/en/reference/flowker/create-workflow) endpoint to define the workflow, then [Activate](/en/reference/flowker/activate-workflow) it, and finally [Execute](/en/reference/flowker/execute-workflow) it.
```json theme={null}
POST /v1/workflows
{
"name": "payment-validation",
"description": "Validates a payment before processing.",
"nodes": [
{
"id": "trigger-payment",
"type": "trigger",
"name": "Payment received",
"position": { "x": 0, "y": 0 },
"data": { "triggerType": "webhook" }
},
{
"id": "check-fraud",
"type": "executor",
"name": "Fraud check",
"position": { "x": 200, "y": 0 },
"data": {
"providerConfigId": "019c96a0-0ac0-7de9-9f53-9cf842a2ee5a",
"endpointName": "score-transaction"
}
},
{
"id": "evaluate-score",
"type": "conditional",
"name": "Score evaluation",
"position": { "x": 400, "y": 0 },
"data": {
"condition": "check-fraud.score < 80"
}
},
{
"id": "approve",
"type": "action",
"name": "Approve payment",
"position": { "x": 600, "y": -100 },
"data": { "action": "log" }
},
{
"id": "reject",
"type": "action",
"name": "Reject payment",
"position": { "x": 600, "y": 100 },
"data": { "action": "log" }
}
],
"edges": [
{ "id": "e1", "source": "trigger-payment", "target": "check-fraud" },
{ "id": "e2", "source": "check-fraud", "target": "evaluate-score" },
{ "id": "e3", "source": "evaluate-score", "target": "approve", "condition": "true" },
{ "id": "e4", "source": "evaluate-score", "target": "reject", "condition": "false" }
]
}
```
```json theme={null}
POST /v1/workflows/{workflowId}/executions
Idempotency-Key: {unique-uuid}
{
"inputData": {
"transactionId": "txn-98765",
"amount": 1500.00,
"currency": "BRL",
"customerId": "cust-12345"
}
}
```
## Triggering workflows
***
Workflow executions are triggered via the [Execute workflow](/en/reference/flowker/execute-workflow) endpoint:
```
POST /v1/workflows/:workflowId/executions
```
The request body contains the `inputData` for the execution. All fields are available to subsequent nodes via the `workflow` namespace — for example, `workflow.transactionId` or `workflow.amount`. Node outputs are available via the node's ID — for example, `check-fraud.score`.
### Idempotency
Every execution request must include an `Idempotency-Key` header. Requests without it are rejected with `400 Bad Request` (error `FLK-0509`). Generate a fresh UUID for each new execution, and reuse the same key only when retrying the identical request.
## Webhook triggers
***
Webhooks are the primary way external systems trigger Flowker workflows. Instead of your system calling the executions API directly, you register a webhook path in a workflow and external services send HTTP requests to that path.
### How it works
1. Add a trigger node of type `webhook` to your workflow with a `path` and `method` in its `data`.
2. When the workflow is activated, Flowker registers the path in its webhook registry.
3. External systems send requests to [`POST /v1/webhooks/{path}`](/en/reference/flowker/trigger-webhook) (or the method you configured).
4. Flowker resolves the path to the matching workflow and executes it.
### Defining a webhook trigger node
The webhook trigger is a node with `type: "trigger"` and the following fields in `data`:
| Field | Type | Required | Description |
| -------------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------- |
| `triggerType` | string | Yes | Must be `"webhook"`. |
| `path` | string | Yes | The webhook path to register (e.g., `"payments/received"`). |
| `method` | string | Yes | HTTP method to match (e.g., `"POST"`). |
| `verify_token` | string | No | Static token for webhook verification. When set, requests must include a matching `X-Webhook-Token` header. |
```json theme={null}
{
"id": "trigger-1",
"type": "trigger",
"name": "Payment Webhook",
"position": { "x": 0, "y": 0 },
"data": {
"triggerType": "webhook",
"path": "payments/received",
"method": "POST",
"verify_token": "my-secret-token"
}
}
```
Once this workflow is activated, external systems can trigger it by sending:
```
POST /v1/webhooks/payments/received
X-Webhook-Token: my-secret-token
Content-Type: application/json
{ "transactionId": "txn-123", "amount": 1500.00 }
```
### Webhook metadata
Flowker automatically injects a `_webhook` object into the execution's `inputData` with metadata about the incoming request:
| Field | Description |
| -------------------- | -------------------------------------------------------------------------------- |
| `_webhook.method` | HTTP method used (e.g., `POST`). |
| `_webhook.path` | The resolved webhook path. |
| `_webhook.headers` | Request headers (excluding `Authorization`, `X-API-Key`, and `X-Webhook-Token`). |
| `_webhook.query` | Query string parameters. |
| `_webhook.remote_ip` | IP address of the caller. |
This metadata is available to all nodes in the workflow via the `workflow._webhook` namespace.
### Important notes
* Each webhook path + method combination can only be registered by one active workflow. Activating a second workflow with the same path fails with a conflict error.
* Webhook paths support nested segments (e.g., `payments/stripe/received`).
* The request body maximum size is 1 MB.
* Deactivating a workflow automatically unregisters its webhook routes.
See the [Trigger a webhook](/en/reference/flowker/trigger-webhook) API reference for the complete endpoint documentation.
### Synchronous response mode
By default, a webhook trigger responds with a `202` receipt as soon as the execution starts (the async mode) — the caller must poll the execution status separately. Set `response_mode` to `"sync"` in the trigger node's `data` to have Flowker hold the HTTP connection open and return the execution's outcome directly in the response:
| Field | Type | Required | Description |
| --------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `response_mode` | string | No | `"async"` (default) returns a `202` receipt immediately. `"sync"` blocks (up to an internal cap) for the execution to reach a terminal state and returns the outcome in the response body. |
| `response_view` | string | No | Shapes the sync response body. Only meaningful when `response_mode` is `"sync"`. See the table below. Defaults to `"full"`. |
If the execution does not reach a terminal state before the internal wait cap elapses, Flowker falls back to the same `202` receipt (with a `Location` header pointing at the results endpoint) the async mode would have returned.
`response_view` selects the shape of the sync response body:
| Value | Description |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `full` (default) | The complete execution dump — `executionId`, `workflowId`, `status`, `stepResults`, `finalOutput` — the same shape you would fetch from the execution results endpoint. |
| `final_output` | Only the execution's `finalOutput` map, with no envelope wrapper. |
| `receipt` | The lean execution receipt (`executionId`, `workflowId`, `status`, `startedAt`) — the same shape the async path returns. |
| `passthrough` | Shapes the response by the **terminal (last-executed) step's node type**. If the terminal step is an executor that captured a provider HTTP response, that response is relayed **verbatim** (status code — including `4xx` — + body + `Content-Type`), bypassing the Flowker envelope. If the terminal step is a `set_output` action with a configured output, the response is that node's business output, honoring its `responseStatusCode` override. If neither applies (no captured provider response — circuit open, timeout, pre-dispatch failure — and no terminal output), it falls back to the full envelope at HTTP `200` so the caller still gets a meaningful outcome. |
A failed execution's `finalOutput` (in `full` or `final_output` view) always carries `status: "failed"` and `errorMessage`, and `errorClass` when Flowker could classify the failure — never a bare `{}`. Absent a `responseStatusCode` override (see below), the sync HTTP status stays `200` for `full`/`final_output`/`receipt` (it reports transport health, not business outcome). A valid `responseStatusCode` on the terminal `set_output` node overrides that status for those three views.
An action node with `actionType: "set_output"` can carry an optional `responseStatusCode` (integer, `200`–`599`) to override the HTTP status a `sync` webhook response returns. An out-of-range or non-integer value is rejected at save time (`FLK-0122`). For `passthrough`, the override applies only when the `set_output` node itself is the terminal step — a terminal executor's relayed provider status always wins, and the no-response fallback always uses a plain `200` so an override never masks a failure.
Passthrough detection is strict: only the terminal step counts. A `set_output` terminal downstream of an executor is shaped as its own output — Flowker never walks back to an earlier executor's response. On a failed execution the halting step is the terminal step, so a provider `4xx` that stopped the workflow is relayed as the real `4xx`.
Values in a `set_output` node's output support `${...}` references resolved against the workflow context — including `${workflow.}` (trigger payload), `${execution.id}`, `${execution.startedAt}`, and `${execution.now}` (stamped at interpolation time). An unresolvable `${...}` reference fails the step (fail-closed).
## Error handling
***
If a node fails, the execution stops and is marked as `failed`.
There is no automatic fallback. After retries are exhausted, the execution fails.
Each failure includes:
* Failed node and reason
* Step number and output
* Error code
| Error code | Meaning | Action |
| ---------- | ---------------------- | ------------------------------------------------- |
| `FLK-0504` | Node execution failed. | Check step results and external service response. |
| `FLK-0507` | Circuit breaker open. | Wait for recovery or check service health. |
## Retry and circuit breaker
***
Flowker includes built-in resilience for executor calls.
### Retries
When an executor call fails with a transient error, Flowker retries automatically. Retry behavior is configurable per node in the executor's configuration:
| Setting | Default | Bounds | Description |
| ----------------------- | ---------------------- | ------------------ | ----------------------------------------------------------------- |
| `timeout_seconds` | 30 | 1–300 | Per-request timeout. |
| `retry.max_attempts` | 3 | 1–5 (platform cap) | Total attempts (initial + retries). |
| `retry.backoff_seconds` | 1 | 1–60 | Initial backoff seed; the wait doubles per attempt (with jitter). |
| `success_status_codes` | `[200, 201, 202, 204]` | 100–599 | HTTP status codes treated as success. |
Retries only apply when the operation is safe to repeat. By default, `POST` and `PATCH` calls are treated as non-idempotent and are **not** retried (a single attempt), while `GET`, `PUT`, `DELETE`, and other verbs retry normally. Setting `retry.max_attempts` explicitly on a node opts that node into retries regardless of method.
**Non-retryable errors** short-circuit to a single attempt regardless of configuration: circuit breaker open, context cancelled, configuration errors, secret-resolution failures, and non-transient `4xx` provider responses (any `4xx` except `408` and `429`).
The retry applies per node execution. If all attempts fail, the step is marked as failed and the execution stops.
### Circuit breaker
Flowker uses a circuit breaker to protect external services from being overwhelmed by repeated failing calls:
| Parameter | Value |
| ------------------ | ---------------------------------------------------------------------- |
| Failure threshold | 20 consecutive failures opens the circuit (configurable at deployment) |
| Recovery timeout | 30 seconds before trying again (half-open state) |
| Half-open requests | 1 request allowed to test if the service recovered |
Provider `4xx` client/auth errors do **not** trip the circuit: they are the caller's problem, not a sign the provider is down. Only transport-level and `5xx` failures count toward the threshold.
When the circuit is open, executor calls fail immediately with `FLK-0507` instead of reaching the external service. This prevents cascading failures and gives the external service time to recover.
The circuit starts in the **Closed** state, where all requests pass through normally. After the failure threshold is reached, it transitions to **Open**, blocking all requests immediately. After 30 seconds, it moves to **Half-Open** and allows one test request. If that request succeeds, the circuit returns to Closed. If it fails, the circuit reopens for another 30-second cycle.
The circuit breaker operates per executor configuration. Failures in one executor do not affect others. Circuit breaker thresholds (failure count, recovery timeout) are global defaults configured at deployment — they cannot be customized per executor in this version.
## What's next
***
Understand workflows, nodes, edges, and executions.
Explore the executor configuration API.