Guía de integración

Conecta servicios externos a Flowker a través de configuraciones de proveedor. Configura la autenticación, mapea campos y ejecuta workflows contra integraciones reales.

Flowker llama a servicios externos (como motores de fraude, procesadores de pago y proveedores de KYC) a través de configuraciones de proveedor. Una configuración de proveedor es tu conexión a una instancia activa de un servicio externo.

En esta guía exploras el catálogo, creas una configuración de proveedor y la referencias desde un nodo de workflow. Después mapeas campos entre tus datos y el servicio, y aprendes cómo Flowker reintenta y protege esas llamadas.

​

Paso 1: Explora el catálogo

---

El catálogo es el registro de los proveedores, los ejecutores del catálogo y los disparadores que vienen con Flowker.

1. Lista los proveedores disponibles

   Llama al endpoint Listar proveedores del catálogo para ver los tipos de servicio a los que Flowker se conecta. El catálogo siempre incluye el conector HTTP genérico. Los proveedores nativos como ledger (Midaz), crm, fees, identity, tracer y pix-jd se sintetizan a partir de especificaciones OpenAPI publicadas y aparecen solo cuando el schema registry nativo está configurado y la síntesis tiene éxito.

2. Lista los ejecutores del catálogo disponibles

   Llama al endpoint Listar ejecutores del catálogo para ver las operaciones que un nodo de workflow puede invocar. Usa Listar ejecutores por proveedor para acotar la lista a un proveedor.

   Un ejecutor creado a partir de una operación OpenAPI trae el method y el path de esa operación. Obtener un ejecutor del catálogo también devuelve sus params: los parámetros de path, query y header que un nodo mapea.

3. Lista los disparadores disponibles

   Llama al endpoint Listar disparadores del catálogo para ver los tipos de disparador integrados: webhooks y programaciones. La API de ejecución de workflow inicia un workflow pero no es un disparador del catálogo.

4. Elige lo que necesitas

   Anota el providerId y el id del ejecutor del catálogo que corresponden a tu integración. Usas el primero en el Paso 2 y el segundo en el Paso 3.

El catálogo muestra lo que Flowker puede llamar. Las configuraciones de proveedor guardan la URL base, las credenciales y los ajustes de cada instancia de servicio que usas.

​

Paso 2: Crea una configuración de proveedor

---

Llama a POST /v1/provider-configurations para definir tu conexión a una instancia de un servicio externo.

Campo	Obligatorio	Descripción
name	Sí	Un nombre para esta conexión, de 1 a 100 caracteres.
kind	No	Qué tipo de conexión es esta. Omítelo, o envía catalog, para una conexión a un proveedor del catálogo (el caso que cubre esta guía). Envía external_openapi para una conexión a un documento de OpenAPI que subiste; consulta Conectar tu propia API. Eliges el tipo cuando creas la configuración.
providerId	Para catalog	El proveedor del catálogo del que esta conexión es una instancia, como ledger o http. Una configuración de tipo external_openapi puede omitirlo, y una lectura de ella devuelve el id reservado external.openapi.
config	Sí	Los detalles de conexión de esa instancia, como la URL base y las credenciales de autenticación. Flowker valida este mapa contra el JSON Schema del proveedor tomado del catálogo y devuelve 422 cuando no coincide.
allowedHosts	Para http	Los hosts públicos que esta configuración puede llamar. El conector HTTP genérico (providerId: "http") requiere al menos una entrada, y una lista vacía se rechaza con FLK-0323. Los proveedores nativos aceptan una lista vacía. Una entrada con un punto inicial coincide con subdominios: .kyc-provider.io coincide con api.kyc-provider.io. Solo nombres de host: nada de literales de IP, comodines ni puertos. El host de config.base_url debe estar cubierto por la lista; de lo contrario, la creación se rechaza con FLK-0320.
allowedPrivateHosts	No	Hosts privados con nombre que Lerian permite que esta configuración alcance. No puedes definirla: una solicitud de tu tenant que define una lista no vacía responde FLK-0317. Las direcciones de metadatos de nube y de link-local siguen bloqueadas.
protected	No	true hace que la configuración sea exclusiva de personas. La defines solo al crear. Consulta Quién puede ejecutar y cambiar un workflow.
schemaBindings	No	Los esquemas XSD u OpenAPI vinculados a esta configuración, cada uno con una restricción opcional a operaciones específicas de OpenAPI.
description	No	Texto libre, hasta 500 caracteres.
metadata	No	Tus propios pares clave-valor.

Un providerId es un identificador del catálogo, y no siempre coincide con el nombre del producto. El catálogo registra Midaz como ledger. Toma siempre el valor de Listar proveedores del catálogo en lugar de adivinarlo a partir del nombre del producto.

El providerId de la configuración y el executorId del nodo que la usa deben pertenecer al mismo proveedor del catálogo. El conector HTTP genérico usa http para ambos. Flowker rechaza un workflow que empareja una configuración de un proveedor con un ejecutor de otro, con FLK-0151.

El ejemplo de abajo construye la conexión que esta guía usa de aquí en adelante: un servicio de puntuación de fraude al que se llega a través del conector HTTP genérico.

Solicitud de ejemplo

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"
  }
}

La respuesta devuelve el id de la nueva configuración. Guárdalo. El Paso 3 y el Paso 4 lo ponen en el providerConfigId del nodo que llama al servicio.

​

Autenticación

El bloque config.auth contiene la autenticación que requiere el servicio externo, como un par { type, config }. Usa el método que espera tu servicio.

Tipo	Descripción	Campos de config
none	Sin autenticación.	—
api_key	API key en header o query.	key, header_name, location, query_param_name, prefix
bearer	Token Bearer en el header Authorization.	token
basic	Nombre de usuario y contraseña (Base64).	username, password
oidc_client_credentials	Flujo de client credentials de OAuth 2.0 con gestión automática del token.	issuer_url, client_id, client_secret, scopes
oidc_user	Flujo de contraseña del propietario del recurso de OAuth 2.0.	issuer_url, client_id, username, password, client_secret, scopes
oauth2_token_endpoint	Client credentials de OAuth 2.0 contra un token endpoint (sin OIDC discovery).	token_url, client_id, client_secret, scopes
hmac	Firma cada solicitud con un secreto HMAC compartido.	secret, algorithm, encoding, header_name, signature_prefix, signing_string, timestamp_header
lerian_token_endpoint	Client ID y secret de una aplicación que tú creas, para los proveedores Midaz ledger, CRM, Fees, Identity y Pix JD.	client_id, client_secret

Una lectura nunca devuelve la credencial que declara el tipo de autenticación. Guarda las credenciales solo en los campos que declara el tipo de autenticación.

Los proveedores ledger, crm, fees, identity y pix-jd llaman a tus propios productos de Lerian con una aplicación que tú creas. Su config guarda solo organization_id, ledger_id y un bloque auth de tipo lerian_token_endpoint con el client_id y el client_secret de esa aplicación. Sin el bloque, crear y actualizar responden FLK-0948, y una ejecución sobre una configuración sin él hace fallar el nodo con FLK-0948. Cualquier otra clave en config responde FLK-0293. El host viene del deployment, así que config no acepta base_url. Para cambiar una configuración existente, envía una actualización cuyo config guarde organization_id, ledger_id y el bloque auth, porque config reemplaza el mapa guardado. La configuración conserva su ID, así que los workflows que la nombran no necesitan edición.

Para rotar un secret, envía el valor nuevo en una actualización. Para conservar el actual, omite el campo o envíalo en blanco. Esto vale mientras la actualización deje todo ajuste de auth que no es secret (ubicación, nombres de header o de parámetro, scopes, token_url, issuer_url), base_url, openapi_schema_id y allowedHosts como están. Una actualización que cambia uno de ellos en una configuración que guarda un secret debe llevar de nuevo todos los valores de secret. De lo contrario, Flowker la rechaza con FLK-0962 y no escribe nada. Una actualización que cambia auth.type debe llevar un valor para cada secret que el tipo nuevo exige, incluido uno que el tipo anterior también usaba. De lo contrario, Flowker la rechaza con FLK-0952.

Para integraciones de OAuth 2.0, usa oidc_client_credentials. Flowker gestiona la obtención y la renovación del token automáticamente.

Ejemplo: client credentials de OIDC

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

​

Habilitar y deshabilitar

Las configuraciones de proveedor tienen dos estados: active (en uso) y disabled (temporalmente fuera de línea). Una nueva configuración de proveedor empieza en estado active. Usa Deshabilitar una configuración de proveedor para sacar una conexión de servicio y Habilitar una configuración de proveedor para devolverla.

Consulta la API de configuraciones de proveedor para la referencia completa.

​

Paso 3: Referencia la configuración de proveedor desde un nodo de workflow

---

Cada nodo ejecutor lleva un providerConfigId, el identificador de la configuración de proveedor a través de la cual llama. Flowker rechaza un workflow cuyo nodo ejecutor no tiene providerConfigId, y rechaza un valor que no es un UUID. En tiempo de ejecución construye cada solicitud saliente a partir de la URL base de esa configuración de proveedor más el path del nodo. El nodo falla si la configuración de proveedor no está active.

Estos son los campos que un nodo ejecutor establece en su objeto data cuando llama a través del conector HTTP genérico:

Campo	Obligatorio	Descripción
executorId	Sí	El ejecutor del catálogo que este nodo invoca, tomado del Paso 1. Flowker rechaza el workflow cuando el id no está en el catálogo. Un nodo que llama a un documento de OpenAPI subido lo omite (ver más abajo).
providerConfigId	Sí	El UUID de la configuración de proveedor a través de la cual llama este nodo.
path	No	El path de la solicitud que se anexa a la URL base de la configuración de proveedor. El host de destino es siempre esa URL base. Un nodo no puede suministrar una URL absoluta.
endpointName	No	Se usa como path de la solicitud cuando el nodo no establece path. Un nodo que lleva ambos envía path.
method	No	GET, POST, PUT, PATCH, DELETE, HEAD u OPTIONS. De forma predeterminada es POST.
headers	No	Headers de la solicitud, fusionados sobre los que define la configuración de proveedor. Un header del nodo gana sobre un header de la configuración de proveedor con el mismo nombre.
query	No	Parámetros de query anexados a la URL.
auth	No	Un bloque de autenticación {type, config} para este nodo, con la misma forma que usa la configuración de proveedor. Cuando está presente tiene precedencia sobre la autenticación de la configuración de proveedor.
body	No	Un cuerpo de solicitud explícito, resuelto contra el contexto del workflow. Cuando se establece, es la única fuente del cuerpo. Los mapeos de campos no se le aplican.
content_digest	No	Un pin SHA-256 para el cuerpo de solicitud ensamblado. Establece un digest hexadecimal de 64 caracteres, o un valor resuelto desde el contexto del workflow. Flowker calcula el hash de los bytes finales después de ensamblar el cuerpo y envía la solicitud solo cuando coinciden.
config	No	Valores literales fijos que siembran el cuerpo de la solicitud. Consulta Mapeo de campos y transformación de datos.
inputMapping, outputMapping, transforms	No	Mapeos de campos y transformaciones. Consulta Mapeo de campos y transformación de datos.
timeout_seconds, retry, success_status_codes	No	Ajustes de resiliencia por nodo. Consulta Reintento y circuit breaker.
request_format	No	Un objeto cuyo type define cómo Flowker serializa el cuerpo de la solicitud: json (el predeterminado), xml_converted o xml_passthrough. xml_converted también requiere root_element.

Un nodo que llama a una operación de un documento de OpenAPI subido la nombra con operation_path y operation_method en lugar de un executorId. Flowker completa el executorId por ti a partir de la configuración de proveedor a la que apunta el nodo. Conectar tu propia API recorre todo ese camino.

​

Valida la configuración de un nodo antes de guardar

Llama al endpoint Validar la configuración de un nodo (POST /v1/catalog/executors/{id}/validate) para verificar la configuración de un nodo contra el JSON Schema del ejecutor del catálogo.

Esto hace solo validación de JSON Schema. Verifica que tu objeto de configuración coincida con la estructura que espera el ejecutor del catálogo (campos obligatorios, tipos, formatos). No llama al servicio externo, así que el primer viaje de ida y vuelta real ocurre cuando un workflow ejecuta el nodo.

Pasa mappedTargets para nombrar los campos que tu nodo suministra a través de un inputMapping en lugar de un valor fijo. Esos campos cuentan como satisfechos, así que un nodo que mapea un campo obligatorio desde el disparador se valida antes de que lo guardes.

​

Mapeo de campos y transformación de datos

---

Usa los mapeos de campos y las transformaciones cuando los datos del workflow no coinciden con el formato que espera un servicio externo. Úsalos también cuando un servicio devuelve datos con una forma que el siguiente paso no puede consumir.

Defines los mapeos de campos y las transformaciones dentro del objeto data de los nodos ejecutores. Flowker aplica los mapeos de entrada antes de llamar al servicio externo, y los mapeos de salida después de recibir la respuesta.

Un target de entrada es una ruta en el cuerpo de la solicitud saliente, escrita exactamente como la espera el servicio externo. No hay objeto envoltorio ni prefijo que agregar. Un source de salida es una ruta dentro del envelope de la respuesta, así que los campos de la respuesta quedan bajo body.

Ejemplo rápido: mapear campos del workflow a un nodo ejecutor

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

Los nodos downstream leen la salida mapeada bajo el ID de este nodo: ${executor-balance.balance}.

Para integraciones complejas, también puedes adjuntar transformaciones a entradas de mapeo individuales (por ejemplo, quitar caracteres, agregar prefijos, cambiar mayúsculas y minúsculas). Puedes definir operaciones de Kazaam para transformaciones avanzadas de JSON a JSON.

Trabajar con datos de solicitud y respuesta recorre todo el camino. Cubre cómo declarar los mapeos, cómo elegir qué construye el cuerpo de la solicitud y cómo reestructurar valores en vuelo. También cubre cómo leer la respuesta de vuelta, y cómo verificar la solicitud ensamblada antes de llamar al servicio.

​

Paso 4: Ejecuta el workflow

---

Referencia la configuración de proveedor en un nodo de workflow de tipo executor.

El ejemplo de abajo crea un workflow de validación de pagos sobre la conexión FraudShield del Paso 2. Cuando llega un pago, Flowker llama al servicio de verificación de fraude, evalúa la puntuación de riesgo y aprueba o rechaza el pago según el resultado.

El workflow tiene cinco nodos. Un disparador de webhook recibe el pago, y un nodo ejecutor llama al servicio de verificación de fraude. Un nodo condicional evalúa la puntuación, y hay dos nodos de acción para los resultados de aprobación y rechazo. Las aristas los conectan en secuencia, y el nodo condicional se ramifica hacia cualquiera de los dos caminos según el umbral de la puntuación.

Usa el endpoint Crear workflow para definir el workflow, luego Actívalo y por último Ejecútalo.

Ejemplo: crear un workflow de validación de pagos

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",
        "inputMapping": [
          { "source": "workflow.transactionId", "target": "transactionId" },
          { "source": "workflow.amount", "target": "amount" }
        ]
      }
    },
    {
      "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" }
  ]
}

El nodo check-fraud nombra http, el conector HTTP genérico del catálogo. También nombra la configuración FraudShield del Paso 2, que contiene la URL base y las credenciales. Ambos lados nombran al mismo proveedor, así que el workflow se guarda. Flowker envía la solicitud a https://api.fraudshield.example.com/score-transaction.

El nodo no declara outputMapping, así que su salida conserva la forma del envelope de la respuesta. Por eso la puntuación queda en check-fraud.body.score, que es lo que lee la condición evaluate-score. Agrega un outputMapping cuando prefieras un nombre más plano. Consulta Mapeo de campos y transformación de datos.

Ejemplo: ejecutar el workflow

POST /v1/workflows/{workflowId}/executions
Idempotency-Key: {unique-uuid}

{
  "inputData": {
    "transactionId": "txn-98765",
    "amount": 1500.00,
    "currency": "BRL",
    "customerId": "cust-12345"
  }
}

​

Disparar workflows

---

Disparas las ejecuciones de workflow mediante el endpoint Ejecutar workflow:

POST /v1/workflows/:workflowId/executions

El cuerpo de la solicitud contiene el inputData de la ejecución. Todos los campos están disponibles para los nodos siguientes mediante el namespace workflow (por ejemplo, workflow.transactionId o workflow.amount). Las salidas de los nodos están disponibles mediante el ID del nodo (por ejemplo, check-fraud.body.score para un nodo que no declara outputMapping).

​

Idempotencia

Toda solicitud Execute workflow debe incluir un header Idempotency-Key. Una solicitud sin él falla con 400 Bad Request (error FLK-0509). Genera un UUID nuevo para cada ejecución nueva y reutiliza la misma clave solo al reintentar la solicitud idéntica. Un reintento en el mismo workflow devuelve la primera ejecución mientras exista: Flowker puede borrar una ejecución finalizada de solo lectura después de la ventana de retención, y la misma clave inicia entonces una ejecución nueva. Una clave que ya usaste en un workflow distinto responde 409 con FLK-0511 y no devuelve nada de esa ejecución.

Un workflow con varios triggers empieza en el trigger indicado por triggerNodeId en el cuerpo de la solicitud. Sin él, o con un nodo que no es uno de los triggers del workflow, la llamada responde 422 con FLK-0515. Un workflow con un solo trigger no necesita nombre. Una ruta de webhook o un trigger de programación inicia la ejecución en su propio nodo de trigger.

​

Disparadores de webhook

---

Los webhooks son la vía principal por la que los sistemas externos disparan workflows de Flowker. En lugar de que tu sistema llame a la API de ejecuciones directamente, registras un path de webhook en un workflow. Los servicios externos envían entonces solicitudes HTTP a ese path.

​

Cómo funciona

1. Agrega a tu workflow un nodo disparador de tipo webhook con un path y un method en su data. Establece input_contract de forma explícita en los nodos nuevos cuando necesites validación open, xsd o openapi.
2. Cuando activas el workflow, Flowker registra el path en su registro de webhooks.
3. Los sistemas externos envían solicitudes a POST /v1/webhooks/{path} (o el método que configuraste).
4. Flowker resuelve el path al workflow correspondiente y lo ejecuta.

​

Definir un nodo disparador de webhook

El disparador de webhook es un nodo con type: "trigger" y triggerType: "webhook" en su data, más un path, un method y un input_contract opcional. Configurar un disparador de webhook cubre cada campo, los tres modos de input_contract y lo que requiere cada uno, y lleva un nodo resuelto para cada modo.

La configuración del disparador sigue un contrato cerrado. Guardar un workflow falla con FLK-0934 cuando su disparador de webhook omite path o method, o le falta un campo que requiere el modo de input_contract seleccionado. También falla cuando el disparador nombra el id de esquema o el campo de operación de otro modo. Falla también cuando el disparador lleva una clave o un valor que el esquema no acepta. Un nombre en accepted_headers que no es un nombre de header válido, repite otro nombre o está en la lista de bloqueo falla con FLK-0957 en su lugar.

El esquema también declara los campos opcionales response_mode, response_view y accepted_headers. Consulta Configurar un disparador de webhook.

​

Asegurar un webhook

Con PLUGIN_AUTH_ENABLED=true, las solicitudes a /v1/webhooks/* requieren un token Bearer y el permiso execute sobre el recurso webhooks. Las implementaciones en producción requieren la autenticación del plugin.

Otorga ese permiso a una identidad máquina a máquina para cada sistema al que dejas llamar a tus webhooks, y gestiona la concesión en Access Manager. Esto mantiene el acceso a los webhooks bajo el mismo modelo de roles y políticas que la gestión de workflows, en lugar de una credencial adjunta al path.

​

Quién puede ejecutar y cambiar un workflow

Un workflow que mueve dinero no debe quedar abierto a todo sistema que alcance su webhook. Dos ajustes lo restringen.

allowedCallers restringe quién ejecuta el workflow. Es una lista de hasta 50 llamadores, cada uno {"kind": "application", "id": "<client ID>"} o {"kind": "user", "id": "<user ID>"}. Una lista vacía deja que cualquier llamador con el permiso execute lo ejecute. Con lista, un llamador fuera de ella que solicita una ejecución nueva recibe 403 FLK-0519, y no se crea ninguna ejecución. Una lista inválida responde 422 FLK-0194. En la actualización, una solicitud que omite el campo conserva la lista, y [] la vacía. Un disparador de programación y un disparador de Streaming Hub no traen llamador, así que nunca ejecutan un workflow que tiene lista. Solo una persona escribe la lista, y una aplicación que envía el campo recibe 403 FLK-0365. Para cambiar la lista de un workflow activo, desactívalo, pásalo a borrador, edítalo y actívalo de nuevo. Mientras está desactivado, los llamadores reciben un rechazo.

Una configuración de proveedor protegida restringe quién la cambia. Envía protected: true al crear la configuración. No se puede definir después. Solo una persona puede crear, actualizar, habilitar, deshabilitar o eliminar una configuración protegida. Una aplicación que lo intenta recibe 403 FLK-0365.

Un paso sobre una configuración de proveedor que fue eliminada tiene el mismo efecto que un paso sobre una configuración protegida: solo una persona puede actualizar, clonar, mover a borrador, activar, desactivar o eliminar ese workflow.

Un workflow con un paso en un proveedor protegido también es protegido:

• Solo una persona puede crearlo, actualizarlo, clonarlo, pasarlo a borrador, activarlo, desactivarlo o eliminarlo. Una aplicación recibe 403 FLK-0365.
• Activarlo con allowedCallers vacío responde 422 FLK-0366.
• Usa solo proveedores protegidos. Mezclarlos con no protegidos responde 422 FLK-0367.

​

Metadatos del webhook

Flowker inyecta automáticamente un objeto _webhook en el inputData de la ejecución con metadatos sobre la solicitud entrante:

Campo	Descripción
_webhook.method	Método HTTP usado (por ejemplo, POST).
_webhook.path	El path de la solicitud después del prefijo de ruta que recibió la llamada (/v1/webhooks/, o /v1/hub/webhooks/ para el ingreso de Streaming Hub), tal como se recibió.
_webhook.headers	Headers de la solicitud, filtrados por una lista de permitidos segura (Content-Type, Accept, User-Agent, X-Request-Id, X-Forwarded-For, Idempotency-Key) más los accepted_headers opcionales de este disparador y, para una ruta openapi, los parámetros de header de su operación. La lista de bloqueo fija bloquea Authorization, Proxy-Authorization, Cookie, Set-Cookie, X-API-Key, X-Auth-Token y X-Webhook-Signature. Los demás headers admitidos se persisten tal cual; nunca admitas nombres que lleven secretos como X-Amz-Security-Token.
_webhook.query	Conserva los nombres de los parámetros de query recibidos. Conserva los valores solo para customerId, page, cursor, limit, offset y sortOrder (sin distinguir mayúsculas y minúsculas); todos los demás valores se almacenan como [redacted].
_webhook.remote_ip	Dirección IP de quien llama.
_webhook.params	Solo en una ruta cuyo path termina en un segmento {name}: el valor de ese segmento, sin escape de URL, en _webhook.params.<name>.

Estos metadatos están disponibles para todos los nodos del workflow mediante el namespace workflow._webhook.

​

Reglas de path y tamaño del cuerpo

• Activar un workflow cuyo path y método de webhook ya es dueño otro workflow falla con FLK-0360. Un workflow es dueño de sus rutas hasta que lo eliminas.
• Los paths de webhook admiten segmentos anidados (por ejemplo, payments/stripe/received).
• Un path puede terminar en un segmento {name}, como orders/{orderId}. Consulta Terminar un path con un parámetro.
• El tamaño máximo del cuerpo de la solicitud es 1 MB.

Consulta la referencia de API Disparar un webhook para la documentación completa del endpoint.

​

Modo de respuesta síncrono

De forma predeterminada, un disparador de webhook responde con un comprobante 202 en cuanto la ejecución empieza (el modo asíncrono). Quien llama debe consultar el estado de la ejecución por separado. Establece response_mode en "sync" en el data del nodo disparador para que Flowker mantenga abierta la conexión HTTP y devuelva el resultado de la ejecución directamente en la respuesta:

Campo	Tipo	Obligatorio	Descripción
response_mode	string	No	"async" (predeterminado) devuelve un comprobante 202 de inmediato. "sync" se bloquea (hasta un límite interno) a la espera de que la ejecución alcance un estado terminal y devuelve el resultado en el cuerpo de la respuesta.
response_view	string	No	Da forma al cuerpo de la respuesta síncrona. Solo tiene sentido cuando response_mode es "sync". Consulta la tabla de abajo. De forma predeterminada es "full".

Si la ejecución no alcanza un estado terminal antes de que transcurra el límite interno de espera, Flowker recurre al comprobante 202 del modo asíncrono, salvo en la vista passthrough, donde responde 504 con el comprobante y la ejecución sigue. Una ejecución detenida en una espera conserva el 202. Ese comprobante lleva un header Location que apunta al endpoint de resultados.

response_view selecciona la forma del cuerpo de la respuesta síncrona:

Valor	Descripción
full (predeterminado)	El volcado completo de la ejecución (executionId, workflowId, status, stepResults, finalOutput), con la misma forma que obtendrías del endpoint de resultados de la ejecución.
final_output	Solo el mapa finalOutput de la ejecución, sin envoltorio de envelope.
receipt	El comprobante de ejecución reducido (executionId, workflowId, status, startedAt), con la misma forma que devuelve el camino asíncrono.
passthrough	Da forma a la respuesta según el tipo de nodo del paso terminal (el último ejecutado). Para un ejecutor terminal que capturó una respuesta del proveedor, devuelve el estado del proveedor y el Content-Type cuando el estado está en success_status_codes del paso. Retransmite como máximo 8 KiB del cuerpo capturado; los cuerpos más largos se truncan. Los cuerpos JSON se decodifican y se vuelven a serializar antes de la captura, así que la retransmisión byte a byte no está garantizada. Si el paso terminal es una acción set_output con una salida configurada, la respuesta es la salida de negocio de ese nodo, respetando su anulación responseStatusCode. Cuando la ejecución falló, la respuesta es HTTP 502 con status, errorMessage y errorClass, y nunca una respuesta de proveedor retransmitida, incluso después de un 2xx del proveedor.

El finalOutput de una ejecución fallida en la vista final_output lleva status: "failed" y errorMessage, y errorClass cuando Flowker pudo clasificar la falla, nunca un {} vacío. Una ejecución fallida responde HTTP 502 en todas las vistas, con el cuerpo que arma cada vista. Para una ejecución completada, sin una anulación responseStatusCode (ver más abajo), el estado HTTP síncrono es 200 para full/final_output/receipt, y un responseStatusCode válido en un nodo set_output que se ejecuta anula ese estado para esas tres vistas. Mientras exista la primera ejecución, un replay de una ejecución fallida con el mismo Idempotency-Key responde el mismo 502 y nunca se ejecuta de nuevo; envía una clave nueva para ejecutarla otra vez. Una entrega de Streaming Hub se identifica por su id de evento: mientras exista la primera ejecución, una reentrega del mismo evento devuelve esa ejecución y nunca ejecuta el workflow de nuevo. Una llamada a /v1/webhooks/ sin Idempotency-Key ejecuta el workflow de nuevo, así que cada paso que mueve dinero necesita una clave de idempotencia derivada del id de negocio, como el X-Idempotency de Midaz.

Un nodo de acción con actionType: "set_output" puede llevar un responseStatusCode opcional (entero, 200–599) para anular el estado HTTP que devuelve una respuesta de webhook sync. Un valor fuera de rango o que no es entero falla al guardar (FLK-0122). Para passthrough, el estado del proveedor retransmitido por un ejecutor terminal gana sobre la anulación.

Un set_output terminal downstream de un ejecutor da forma a la respuesta como su propia salida. Flowker nunca retrocede a la respuesta de un ejecutor anterior. Una ejecución fallida responde 502, sea cual sea el estado que devolvió el proveedor.

Los valores de la salida de un nodo set_output admiten referencias ${...} resueltas contra el contexto del workflow, incluidas ${workflow.<field>} (payload del disparador), ${execution.id}, ${execution.startedAt} y ${execution.now} (sellado en el momento de la interpolación). Una referencia ${...} que no se puede resolver hace fallar el paso (fail-closed).

​

Tratamiento de errores

---

Si un nodo falla, la ejecución se detiene y su estado pasa a failed.

No hay respaldo automático. Después de que se agotan los reintentos, la ejecución falla.

Los resultados de la ejecución reportan el status de la ejecución y los stepResults. Un paso fallido proporciona stepNumber, nodeId, status y errorMessage, con statusCode y errorClass cuando están disponibles. El campo output es opcional.

​

Reintento y circuit breaker

---

Flowker incluye resiliencia integrada para las llamadas de ejecutor.

​

Reintentos

Cuando una llamada de ejecutor falla con un error transitorio (un error de red, un timeout en el intento, cualquier estado 5xx, o el estado 408 o 429), Flowker reintenta automáticamente. El comportamiento de reintento se configura por nodo, en el data del nodo ejecutor:

Ajuste	Predeterminado	Límites	Descripción
timeout_seconds	30	1–300	Timeout por solicitud.
retry.max_attempts	3 (1 para POST y PATCH sin configurar)	1–10 aceptados; 1–5 efectivos	Acepta 1–10 en el esquema del nodo, pero Flowker limita la cantidad efectiva de intentos en tiempo de ejecución a 1–5.
retry.backoff_seconds	1	1–60	Primer techo de backoff; cada espera es un valor aleatorio entre cero y el techo, que se duplica por intento.
success_status_codes	[200, 201, 202, 204]	100–599	Códigos de estado HTTP tratados como éxito.

Los reintentos aplican solo cuando la operación es segura de repetir. De forma predeterminada, Flowker trata las llamadas POST y PATCH como no idempotentes y no las reintenta (un solo intento), mientras que GET, PUT, DELETE y los demás verbos reintentan con normalidad. Un retry.max_attempts mayor que 1 activa los reintentos en ese nodo sea cual sea el método. Un retry.max_attempts de 1 no es una activación. Establece un solo intento.

Los errores no reintentables cortocircuitan a un solo intento sin importar la configuración. Entre ellos están circuit breaker abierto, contexto cancelado y fallas de resolución de secretos. También incluyen un cuerpo de solicitud que supera el límite de tamaño configurado, un cuerpo de respuesta del proveedor que supera ese mismo límite y respuestas 4xx no transitorias del proveedor. Eso significa cualquier 4xx salvo 408 y 429.

El reintento aplica por ejecución de nodo. Si todos los intentos fallan, el paso falla y la ejecución se detiene.

​

Circuit breaker

Flowker usa un circuit breaker para que las llamadas fallidas repetidas no saturen los servicios externos:

Parámetro	Valor
Umbral de fallas	20 fallas consecutivas abren el circuito
Timeout de recuperación	30 segundos antes de volver a intentar (estado half-open)
Solicitudes en half-open	1 solicitud permitida para probar si el servicio se recuperó

Una respuesta 4xx del proveedor no cuenta para el umbral, salvo 408 y 429: refleja la solicitud, no la salud del proveedor.

Una respuesta 5xx del proveedor cuenta, incluso cuando el proveedor la envía a propósito por un resultado de negocio. Ejemplo: un plugin Pix que responde 500 para que el remitente reenvíe un crédito que estacionó. Dele al workflow que retransmite esas respuestas su propia configuración de proveedor. Su circuito se abre solo, y sus otras llamadas al mismo proveedor siguen pasando.

Cuando el circuito está abierto, las llamadas de ejecutor fallan de inmediato con FLK-0507 en lugar de llegar al servicio externo. Esto evita las fallas en cascada y da tiempo al servicio externo para recuperarse.

Transiciones de estado del circuit breaker

El circuito empieza en el estado Closed, donde todas las solicitudes pasan con normalidad. Después de que el circuito alcanza el umbral de fallas, transita a Open y bloquea todas las solicitudes de inmediato. Después de 30 segundos, pasa a Half-Open y permite una solicitud de prueba. Si esa solicitud tiene éxito, el circuito vuelve a Closed. Si falla, el circuito se vuelve a abrir por otro ciclo de 30 segundos.

El circuit breaker opera por configuración de proveedor, acotado a tu tenant. Las fallas contra una conexión no afectan a otra, y un tenant no puede abrir el circuito de otro. Los umbrales del circuit breaker (cantidad de fallas, timeout de recuperación) son valores predeterminados globales del despliegue. No puedes personalizarlos por conexión.

​

Qué sigue

---

Conceptos centrales

Entiende los workflows, los nodos, las aristas y las ejecuciones.

API de configuraciones de proveedor

Explora la API de configuración de proveedor.