Integration guide

Connect external services to Flowker through provider configurations. Set up authentication, map fields, and run workflows against real integrations.

Flowker calls external services (such as fraud engines, payment processors, and KYC providers) through provider configurations. A provider configuration is your connection to one live instance of an external service.

In this guide, you explore the catalog, create a provider configuration, reference it from a workflow node, map fields between your data and the service, and learn how Flowker retries and protects those calls.

Step 1: Explore the catalog

---

The catalog is a read-only registry of the providers, catalog executors, and triggers that ship with Flowker. You discover them; you never create them.

1. List available providers

   Call the List catalog providers endpoint to see the service types Flowker connects to. The catalog always includes the generic HTTP connector. Native providers such as ledger (Midaz) and tracer are synthesized from published OpenAPI specifications and appear only when the native schema registry is configured and synthesis succeeds.

2. List available catalog executors

   Call the List catalog executors endpoint to see the operations a workflow node can invoke. Use List executors by provider to narrow the list to one provider.

3. List available triggers

   Call the List catalog triggers endpoint to see the built-in trigger types: webhooks and schedules. The Execute workflow API starts a workflow but is not a catalog trigger.

4. Pick what you need

   Note the providerId and the catalog executor id that match your integration. You use the first in Step 2 and the second in Step 3.

Think of the catalog as a menu: it shows what Flowker can call. Provider configurations are your specific orders — the base URL, the credentials, and the settings for each service instance you use.

Step 2: Create a provider configuration

---

Call POST /v1/provider-configurations to define your connection to one instance of an external service.

Field	Required	Description
name	Yes	A name for this connection, 1–100 characters.
kind	No	Which kind of connection this is. Omit it, or send catalog, for a connection to a catalog provider — the case this guide covers. Send external_openapi for a connection to an OpenAPI document you uploaded; see Connecting your own API. You choose the kind when you create the configuration.
providerId	For catalog	The catalog provider this connection is an instance of, such as ledger or http. A configuration of kind external_openapi may omit it, and a read of it returns the reserved id external.openapi.
config	Yes	The connection details for that instance, such as the base URL and the authentication credentials. Flowker validates this map against the provider’s JSON Schema from the catalog and returns 422 when it does not match. The secret inside the auth block is held in your secrets backend, not in the configuration document; everything else in the map is stored with the configuration.
allowedHosts	For http	The public hosts this configuration is allowed to call. The generic HTTP connector (providerId: "http") requires at least one entry, and an empty list is rejected with FLK-0323. Native providers accept an empty list. An entry with a leading dot matches subdomains — .kyc-provider.io matches api.kyc-provider.io. Host names only: no IP literals, wildcards, or ports. The host in config.base_url must be covered by the list, otherwise the create is rejected with FLK-0320.
allowedPrivateHosts	No	Named private hosts your operations team allows this configuration to reach. Cloud metadata and link-local addresses stay blocked.
schemaBindings	No	The XSD or OpenAPI schemas bound to this configuration, each with an optional restriction to specific OpenAPI operations.
description	No	Free text, up to 500 characters.
metadata	No	Your own key-value pairs.

A providerId is a catalog identifier, and it does not always match the product name. Midaz is registered as ledger. Always take the value from List catalog providers rather than guessing it from the product name.

The providerId on the configuration and the executorId on the node that uses it must belong to the same catalog provider. The generic HTTP connector uses http for both. A workflow that pairs a configuration of one provider with an executor of another is rejected with FLK-0151.

The example below builds the connection this guide uses from here on: a fraud scoring service reached through the generic HTTP connector.

Example request

POST /v1/provider-configurations

{
  "name": "FraudShield Production",
  "description": "Production fraud scoring service",
  "providerId": "http",
  "config": {
    "base_url": "https://api.fraudshield.example.com",
    "auth": {
      "type": "api_key",
      "config": {
        "key": "sk-prod-xxx",
        "header_name": "X-API-Key",
        "location": "header"
      }
    }
  },
  "allowedHosts": ["api.fraudshield.example.com"],
  "metadata": {
    "environment": "production"
  }
}

The response returns the new configuration’s id. Keep it — Step 3 and Step 4 put it in the providerConfigId of the node that calls the service.

Authentication

The config.auth block holds the authentication the external service requires, as a { type, config } pair. Use the method your service expects.

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
hmac	Signs each request with a shared HMAC secret.	secret, algorithm, encoding, header_name, signature_prefix, signing_string, timestamp_header

Secret leaves in config.auth are stored outside the persisted configuration document. An authorized provider-configuration read can resolve those values from the vault and return them in clear; leaves that are not resolved remain masked. Grant read access accordingly.

Anything else you place in the configuration document — a header, for example — is stored with the configuration, and a read can return it. Put each credential in config.auth.

To rotate a secret, send the new value in an update. To keep the current one, omit the field or send it blank — this works while auth.type stays the same. An update that changes auth.type must carry a value for each secret the new type requires and the previous one did not, otherwise Flowker rejects it with FLK-0952. A change between two types that use the same secret, such as oidc_user to oidc_client_credentials, does not need that value again.

For OAuth 2.0 integrations, use oidc_client_credentials. Flowker handles token acquisition and renewal automatically.

Example — OIDC client credentials

{
  "auth": {
    "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"]
    }
  }
}

Enabling and disabling

Provider configurations have two statuses: active (in use) and disabled (temporarily offline). They are created in active status. Use Disable provider configuration to take a connection out of service and Enable provider configuration to bring it back.

See the Provider configurations API for the full reference.

Step 3: Reference the provider configuration from a workflow node

---

Every executor node carries a providerConfigId — the identifier of the provider configuration it calls through. Flowker rejects a workflow whose executor node has no providerConfigId, and rejects a value that is not a UUID. At run time it builds each outgoing request from the base URL of that provider configuration plus the path on the node, and the node fails if the provider configuration is not active.

These are the fields an executor node sets in its data object when it calls through the generic HTTP connector:

Field	Required	Description
executorId	Yes	The catalog executor this node invokes, taken from Step 1. Flowker rejects the workflow when the id is not in the catalog. A node that calls an uploaded OpenAPI document omits it — see below.
providerConfigId	Yes	The UUID of the provider configuration this node calls through.
path	No	The request path appended to the provider configuration’s base URL. The destination host is always that base URL — a node cannot supply an absolute URL.
endpointName	No	The same request segment by name, used when the node sets no path. A node that carries both sends path.
method	No	GET, POST, PUT, PATCH, DELETE, HEAD, or OPTIONS. Defaults to POST.
headers	No	Request headers, merged over the ones the provider configuration defines. A node header wins over a provider-configuration header of the same name.
query	No	Query parameters appended to the URL.
auth	No	A {type, config} authentication block for this node, in the same shape the provider configuration uses. When present it takes precedence over the authentication on the provider configuration.
body	No	An explicit request body, resolved against the workflow context. When set, it is the only body source — field mappings are not applied to it.
config	No	Fixed literal values that seed the request body. See Field mapping and data transformation.
inputMapping, outputMapping, transforms	No	Field mappings and transformations. See Field mapping and data transformation.
timeout_seconds, retry, success_status_codes	No	Per-node resilience settings. See Retry and circuit breaker.
request_format	No	How Flowker serializes the request body: json (the default), xml_converted, or xml_passthrough. xml_converted also requires root_element.

A node that calls an operation of an uploaded OpenAPI document names it with operation_path and operation_method instead of an executorId. Flowker fills the executorId in for you from the provider configuration the node points at. Connecting your own API walks that whole path.

Validate a node configuration before you save

Call the Validate a node configuration endpoint (POST /v1/catalog/executors/{id}/validate) to check a node’s configuration against the catalog executor’s JSON Schema.

This performs JSON Schema validation only — it checks that your configuration object matches the structure the catalog executor expects (required fields, types, formats). It does not call the external service, so the first real round trip happens when a workflow runs the node.

Pass mappedTargets to name the fields your node supplies through an inputMapping rather than a fixed value. Those fields count as satisfied, so a node that maps a required field from the trigger validates before you save it.

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.

An input target is a path in the outgoing request body, written exactly as the external service expects it — there is no wrapper object and no prefix to add. An output source is a path into the response envelope, so response fields sit under body.

Quick example — mapping workflow fields to an executor node

{
  "id": "executor-balance",
  "type": "executor",
  "name": "Check Balance",
  "data": {
    "executorId": "http",
    "providerConfigId": "a1b2c3d4-e5f6-4789-a012-345678901234",
    "path": "/accounts/balance",
    "inputMapping": [
      { "source": "workflow.customerId", "target": "accountId" },
      { "source": "workflow.amount", "target": "minimumBalance" }
    ],
    "outputMapping": [
      { "source": "body.currentBalance", "target": "balance" },
      { "source": "body.accountStatus", "target": "status" }
    ]
  }
}

Downstream nodes read the mapped output under this node’s ID: ${executor-balance.balance}.

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.

Working with request and response data walks the whole path: declaring the mappings, choosing what builds the request body, reshaping values in flight, reading the response back out, and checking the assembled request before you call the service.

Step 4: Run the workflow

---

Reference the provider configuration in a workflow node of type executor.

The example below creates a payment validation workflow on top of the FraudShield connection from Step 2. When a payment arrives, Flowker calls the fraud check service, 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 endpoint to define the workflow, then Activate it, and finally Execute it.

Example — Create a payment validation workflow

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",
        "path": "payments/received",
        "method": "POST",
        "input_contract": "open",
        "format": "json"
      }
    },
    {
      "id": "check-fraud",
      "type": "executor",
      "name": "Fraud check",
      "position": { "x": 200, "y": 0 },
      "data": {
        "executorId": "http",
        "providerConfigId": "019c96a0-0ac0-7de9-9f53-9cf842a2ee5a",
        "path": "/score-transaction",
        "method": "POST"
      }
    },
    {
      "id": "evaluate-score",
      "type": "conditional",
      "name": "Score evaluation",
      "position": { "x": 400, "y": 0 },
      "data": {
        "condition": "check-fraud.body.score < 80"
      }
    },
    {
      "id": "approve",
      "type": "action",
      "name": "Approve payment",
      "position": { "x": 600, "y": -100 },
      "data": {
        "actionType": "set_output",
        "output": { "decision": "approved" }
      }
    },
    {
      "id": "reject",
      "type": "action",
      "name": "Reject payment",
      "position": { "x": 600, "y": 100 },
      "data": {
        "actionType": "set_output",
        "output": { "decision": "rejected" }
      }
    }
  ],
  "edges": [
    { "id": "e1", "source": "trigger-payment", "target": "check-fraud" },
    { "id": "e2", "source": "check-fraud", "target": "evaluate-score" },
    { "id": "e3", "source": "evaluate-score", "target": "approve", "sourceHandle": "true" },
    { "id": "e4", "source": "evaluate-score", "target": "reject", "sourceHandle": "false" }
  ]
}

The check-fraud node names http — the generic HTTP connector from the catalog — and the FraudShield configuration created in Step 2, which holds the base URL and the credentials. Both sides name the same provider, so the workflow saves. Flowker sends the request to https://api.fraudshield.example.com/score-transaction.

The node declares no outputMapping, so its output keeps the response envelope shape. The score therefore sits at check-fraud.body.score, which is what the evaluate-score condition reads. Add an outputMapping when you prefer a flatter name — see Field mapping and data transformation.

Example — Execute the workflow

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 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.body.score for a node that declares no outputMapping.

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, a method, and an input_contract 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} (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 triggerType: "webhook" in its data, plus a path, a method and an input_contract. Configuring a webhook trigger covers every field, the three input_contract modes and what each one requires, and carries a worked node for each mode.

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. The schema also declares the optional response_mode and response_view fields — see Synchronous response mode.

Securing a webhook

Webhook delivery uses the same authentication as the rest of the API. With Access Manager enabled (PLUGIN_AUTH_ENABLED=true), every request to /v1/webhooks/* must carry a Bearer token (OIDC JWT), and the caller must hold the execute permission on the webhooks resource. Requests without a valid token are rejected with 401 Unauthorized.

Grant that permission to a machine-to-machine identity for each system you let call your webhooks, and manage the grant in Access Manager. This keeps webhook access under the same role and policy model as workflow management, rather than a credential attached to the path.

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, filtered through a safe allowlist (Content-Type, Accept, User-Agent, X-Request-Id, X-Forwarded-For, Idempotency-Key). All other headers are dropped.
_webhook.query	Preserves the names of received query parameters. It preserves values only for customerId, page, cursor, limit, offset, and sortOrder (case-insensitive); every other value is stored as [redacted].
_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 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. For a terminal executor that captured a provider response, it returns the provider status (including 4xx) and Content-Type. It relays at most 8 KiB of the captured body; longer bodies are truncated. JSON bodies are decoded and re-serialized before capture, so byte-for-byte relay is not guaranteed. 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.<field>} (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.

Execution results report the execution status and stepResults. A failed step provides stepNumber, nodeId, status, and errorMessage, with statusCode and errorClass when available; output is optional. Do not promise an errorCode, including FLK-0504 or FLK-0507, in every execution-results payload.

Retry and circuit breaker

---

Flowker includes built-in resilience for executor calls.

Retries

When an executor call fails with a transient error — a network error, a timeout on the attempt, any 5xx status, or status 408 or 429 — Flowker retries automatically. Retry behavior is configurable per node, in the executor node’s data:

Setting	Default	Bounds	Description
timeout_seconds	30	1–300	Per-request timeout.
retry.max_attempts	3 (1 for unconfigured POST and PATCH)	1–10 accepted; 1–5 effective	Accepts 1–10 in the node schema, but Flowker clamps the effective runtime attempt count to 1–5.
retry.backoff_seconds	1	1–60	First backoff ceiling; each wait is a random value between zero and the ceiling, which doubles per attempt.
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. A retry.max_attempts greater than 1 opts that node into retries whatever the method is. A retry.max_attempts of 1 is not an opt-in — it sets a single attempt.

Non-retryable errors short-circuit to a single attempt regardless of configuration: circuit breaker open, context cancelled, configuration errors, secret-resolution failures, a request body over the configured size cap, a provider response body over the same cap, 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.

Circuit breaker state transitions

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 provider configuration, scoped to your tenant. Failures against one connection do not affect another, and one tenant cannot open the circuit for another. Circuit breaker thresholds (failure count, recovery timeout) are global defaults configured at deployment — they cannot be customized per connection in this version.

Executor configuration registry

---

This registry is a third, separate use of the word “executor”: its records are not the catalog executors of Step 1, not the workflow nodes of type: "executor", and not the provider configurations of Step 2. The engine reads provider configurations to call external services, not these records, and the registry carries its own field vocabulary (baseUrl, endpoints, authentication). The registry exposes four operations:

Operation	Endpoint
List	GET /v1/executors
Get	GET /v1/executors/{id}
Update	PATCH /v1/executors/{id}
Delete	DELETE /v1/executors/{id}

Every record carries a status, which the API reports in each response:

Status	Description
unconfigured	The record has no connection details yet.
configured	The record carries connection details.
tested	The record was verified.
active	The record is in service.
disabled	The record is out of service.

PATCH accepts name, baseUrl, endpoints, and authentication, plus the optional description and metadata. It does not accept status, but the list operation accepts status as a query filter. Update applies to records in unconfigured or configured status; delete applies to records in unconfigured, configured, or disabled status. No operation in this version moves a record into tested, active, or disabled; the table lists those values because responses report them and the list filter accepts them.

What’s next

---

Core concepts

Understand workflows, nodes, edges, and executions.

Provider configurations API

Explore the provider configuration API.