Integration guide

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.

List available executors

Call the List catalog executors endpoint to see all executor types Flowker supports out of the box — HTTP requests, data transformations, and more.

List available triggers

Call the List catalog triggers endpoint to see how workflows can be started — webhooks or manual API calls.

Pick what you need

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) in Step 1. 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 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 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`
Get	`GET /v1/executors/{id}`
Update	`PATCH /v1/executors/{id}`
Delete	`DELETE /v1/executors/{id}`

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 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`, `value`, `location`
`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.	`tokenURL`, `clientID`, `clientSecret`, `scopes`
`oidc_user`	OAuth 2.0 resource owner password flow.	`tokenURL`, `clientID`, `clientSecret`, `username`, `password`, `scopes`

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

Example — OIDC client credentials

{
  "authentication": {
    "type": "oidc_client_credentials",
    "config": {
      "tokenURL": "https://auth.fraudshield.com/oauth/token",
      "clientID": "flowker-integration",
      "clientSecret": "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 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.

Example request

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 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 endpoint and re-enable it later with the Enable provider configuration endpoint. See the Provider configurations API for the full reference.

Step 3: Configure the executor

Mark the executor as configured by calling the 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 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 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.

Quick example — mapping workflow fields to an executor

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

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.score.

Idempotency

To prevent duplicate executions, include an Idempotency-Key header in the request. If no Idempotency-Key is provided, duplicate protection is not guaranteed.

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

Add a trigger node of type webhook to your workflow with a path and method in its data.
When the workflow is activated, Flowker registers the path in its webhook registry.
External systems send requests to POST /v1/webhooks/{path} (or the method you configured).
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.

Example — Webhook trigger node

{
  "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 API reference for the complete endpoint documentation.

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:

Max retries: 5 attempts
Backoff strategy: Exponential — 1s, 2s, 4s, 8s
Non-retryable errors: Circuit breaker open, context cancelled, invalid configuration

The retry applies per node execution. If all 5 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	5 consecutive failures opens the circuit
Recovery timeout	30 seconds before trying again (half-open state)
Half-open requests	1 request allowed to test if the service recovered

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 5 consecutive failures, 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 startup — they cannot be customized per executor in this version.

Introduction

Guides

Operations

Integration guide

Executor configuration lifecycle

Step 1: Explore the catalog

Step 2: Configure a provider connection and executor

Create a provider configuration

Manage executor configurations

Authentication types

Provider configurations

Creating a provider configuration

Testing connectivity

Enabling and disabling

Step 3: Configure the executor

Step 4: Validate your configuration

Field mapping and data transformation

Step 5: Use the executor in a workflow

Using an executor in a workflow

Triggering workflows

Idempotency

Webhook triggers

How it works

Defining a webhook trigger node

Webhook metadata

Important notes

Error handling

Retry and circuit breaker

Retries

Circuit breaker

What’s next

Core concepts

Executor configurations API

Introduction

Guides

Operations

​Executor configuration lifecycle

​Step 1: Explore the catalog

​Step 2: Configure a provider connection and executor

​Create a provider configuration

​Manage executor configurations

​Authentication types

​Provider configurations

​Creating a provider configuration

​Testing connectivity

​Enabling and disabling

​Step 3: Configure the executor

​Step 4: Validate your configuration

​Field mapping and data transformation

​Step 5: Use the executor in a workflow

​Using an executor in a workflow

​Triggering workflows

​Idempotency

​Webhook triggers

​How it works

​Defining a webhook trigger node

​Webhook metadata

​Important notes

​Error handling

​Retry and circuit breaker

​Retries

​Circuit breaker

​What’s next

Core concepts

Executor configurations API

Executor configuration lifecycle

Step 1: Explore the catalog

Step 2: Configure a provider connection and executor

Create a provider configuration

Manage executor configurations

Authentication types

Provider configurations

Creating a provider configuration

Testing connectivity

Enabling and disabling

Step 3: Configure the executor

Step 4: Validate your configuration

Field mapping and data transformation

Step 5: Use the executor in a workflow

Using an executor in a workflow

Triggering workflows

Idempotency

Webhook triggers

How it works

Defining a webhook trigger node

Webhook metadata

Important notes

Error handling

Retry and circuit breaker

Retries

Circuit breaker

What’s next