Configurar un disparador de webhook

Un disparador de webhook es el punto de entrada de un workflow que empieza con una llamada HTTP entrante. Declaras un path y un método en el nodo disparador. Cuando activas el workflow, Flowker sirve ese path. Cada llamada nueva aceptada inicia una ejecución del workflow. Una repetición con la misma Idempotency-Key devuelve en su lugar la ejecución existente. El input_contract opcional decide qué payloads acepta Flowker y cómo los decodifica. Defínelo de forma explícita en los nodos nuevos: fija el formato de payload de toda la ruta. Los nodos antiguos que lo omiten siguen siendo válidos. Flowker deriva xsd cuando llevan un esquema XSD y formato XML. Si no, Flowker los trata como open con JSON como formato predeterminado.

Antes de empezar

Un workflow en estado draft. Un workflow activo está bloqueado, así que agrega el disparador antes de activarlo. Consulta Primeros pasos con Flowker para el recorrido de creación y activación.
Con PLUGIN_AUTH_ENABLED=true (obligatorio en producción), otorga el permiso execute sobre el recurso webhooks a cada sistema al que le permitas llamar al path. Consulta Proteger un webhook. Un despliegue fuera de producción con la autenticación de plugin deshabilitada usa un passthrough que no autoriza.
Para el contrato xsd: un documento XSD en el registro. Súbelo con Subir un esquema XSD y guarda el id que devuelve. Para hacer cumplir la validación XSD de entrada, configura el servicio de validación XML mediante XSD_VALIDATOR_URL. Cuando no está definida, Flowker decodifica XML bien formado pero omite la validación XSD.
Para el contrato openapi: un documento OpenAPI en el registro (Subir un esquema OpenAPI, cubierto de punta a punta en Conectar tu propia API). También necesitas el path y el método de la operación cuyo cuerpo de solicitud describe tu payload. Derivar el esquema de una operación te muestra ese cuerpo de solicitud.

Paso 1: Lee el contrato del disparador en el catálogo

Los disparadores vienen incorporados. Los descubres en el catálogo, y nunca creas uno.

Lista los disparadores incorporados

Listar disparadores del catálogo devuelve cada disparador con su id, name y version. El id del disparador de webhook es webhook.

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

Lee el esquema del disparador de webhook

Obtener un disparador del catálogo devuelve los mismos campos más schema, el JSON Schema contra el que Flowker valida tu nodo disparador. Léelo cuando quieras la lista de campos desde la instancia en ejecución.

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

Paso 2: Elige el contrato de entrada

Modo	Qué acepta la ruta	Qué hace Flowker con el payload	Campos que exige el modo
`open`	JSON o XML, según lo declares en `format`	Decodifica el cuerpo y no ejecuta validación de contrato.	`format` — `"json"` o `"xml"`
`xsd`	XML	Con la validación XSD configurada, valida el documento contra el esquema XSD que referenciaste. Sin ella, Flowker decodifica XML bien formado pero omite la validación XSD.	`xsd_schema_id`
`openapi`	JSON	Valida el payload contra exactamente una operación del documento OpenAPI que referenciaste, y rechaza un payload que no cumple.	`openapi_schema_id`, `operation_path`, `operation_method`

El modo fija el formato de payload de la ruta. Una ruta xsd es XML y una ruta openapi es JSON. Una ruta open usa el format que declaras. El validador actualmente también acepta format en xsd y openapi. Esos modos lo ignoran y fuerzan XML o JSON respectivamente. Omítelo ahí para que la configuración no dé a entender que cambia la ruta. Elige open cuando el payload de quien llama no tiene un contrato publicado, o cuando quieres que el propio workflow decida qué es aceptable. Cuando un socio envía XML que define un documento XSD, elige xsd. Elige openapi cuando un socio envía JSON y tú tienes el documento OpenAPI que lo describe.

Una ruta openapi nunca acepta un payload sin verificar: cuando Flowker no puede llegar a un veredicto, rechaza la llamada con FLK-0720, y el workflow nunca ve ese payload. Cuando la validación XSD está configurada, una ruta xsd llega a su veredicto a través de ese servicio. Un documento que no cumple se rechaza con XML_VALIDATION_FAILED. Flowker rechaza con FLK-0720 un veredicto en el que no puede confiar. Configura ese servicio antes de poner una ruta xsd frente a quien llame y exija el cumplimiento del esquema.

Paso 3: Decide cómo responde el webhook

`response_mode`	Qué recibe quien llama
`async` (predeterminado)	Para una ejecución nueva y no terminal, HTTP `202` con el comprobante de la ejecución apenas empieza. El workflow continúa en segundo plano, y quien llama lee el resultado en Obtener resultados de ejecución. Si la ejecución resuelta ya es terminal, incluida una repetición con `Idempotency-Key`, Flowker devuelve el comprobante con HTTP `200` y metadatos de repetición.
`sync`	Flowker mantiene la conexión hasta que la ejecución alcanza un estado terminal, durante un máximo de 15 segundos, y luego devuelve el resultado. Si la ventana se cierra antes, quien llama recibe el mismo comprobante `202` más un header `Location` que apunta al endpoint de resultados.

En una ruta sync, response_view da forma al cuerpo:

`response_view`	Cuerpo
`full` (predeterminado)	El envelope completo de resultados de ejecución: `executionId`, `workflowId`, `status`, `stepResults`, `finalOutput` cuando está disponible, `startedAt`, `completedAt` e `inputData` opcionales, más metadatos de repetición por idempotencia cuando corresponde.
`final_output`	Para una ejecución completada, solo el mapa de salida de negocio final (`{}` cuando no está). Para una ejecución fallida, un objeto de falla con `status: "failed"` y, cuando están disponibles, `errorMessage` y `errorClass`.
`receipt`	El comprobante reducido: `executionId`, `workflowId`, `status` y `startedAt`.
`passthrough`	La forma que implica el paso terminal — una respuesta de proveedor retransmitida, o la salida propia de un nodo `set_output` terminal.

response_view es inerte en una ruta async. Para las reglas completas de passthrough y para la anulación con responseStatusCode, consulta Modo de respuesta síncrona.

Elige async cuando quien llama solo necesita saber que el evento llegó. Elige sync cuando quien llama necesita la respuesta en la misma llamada (un socio que espera una decisión en la misma conexión, por ejemplo).

Paso 4: Escribe el nodo disparador

El disparador de webhook es un nodo con type: "trigger" y estos campos en su data:

Campo	Cuándo lo defines	Valor
`triggerType`	Siempre	`"webhook"`.
`path`	Siempre	El path a servir, como `"payments/received"`. Lleva tantos segmentos como necesites.
`method`	Siempre	El método al que responde la ruta: `GET`, `POST`, `PUT`, `PATCH` o `DELETE`, en mayúsculas.
`input_contract`	Opcional	`"open"`, `"xsd"` u `"openapi"`. Defínelo de forma explícita en los nodos nuevos. Cuando se omite, aplican las reglas heredadas.
`format`	Con `open`	Obligatorio y efectivo solo con `open`: `"json"` o `"xml"`. El validador actualmente lo acepta con `xsd` y `openapi`, donde se ignora.
`xsd_schema_id`	Con `xsd`	El id que devolvió Subir un esquema XSD.
`openapi_schema_id`	Con `openapi`	El id que devolvió Subir un esquema OpenAPI.
`operation_path`	Con `openapi`	El path de la operación tal como lo escribe el documento OpenAPI, como `"/orders"`. Flowker lo compara de forma exacta.
`operation_method`	Con `openapi`	El método de la operación: `GET`, `POST`, `PUT`, `PATCH` o `DELETE`.
`response_mode`	Opcional	`"async"` (predeterminado) o `"sync"`.
`response_view`	Opcional	`"full"` (predeterminado), `"final_output"`, `"receipt"` o `"passthrough"`.
`accepted_headers`	Opcional	Hasta 50 nombres extra de headers de solicitud para persistir en `_webhook.headers`, en todos los modos de contrato. Los nombres deben ser únicos sin distinguir mayúsculas de minúsculas; cada uno debe ser un nombre de header HTTP no vacío, de como máximo 256 caracteres. La lista de bloqueo fija rechaza `Authorization`, `Proxy-Authorization`, `Cookie`, `Set-Cookie`, `X-API-Key` y `X-Auth-Token`; no detecta credenciales en otros headers. Nunca permitas otro nombre que lleve secretos, como `X-Amz-Security-Token`.

La configuración del disparador es un contrato cerrado. Un guardado falla con FLK-0934 cuando el disparador de webhook:

omite path o method
no tiene un campo que exige el modo input_contract seleccionado
nombra el id de esquema o el campo de operación de otro modo
lleva una clave o un valor que el esquema rechaza

Una declaración accepted_headers inválida falla con FLK-0957 en su lugar.

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

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

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

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

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

Flowker registra el path con una barra inicial y sin una final, así que payments/received, /payments/received y payments/received/ registran todos la misma ruta.

Paso 5: Activa el workflow

Crea el workflow

Envía el nodo con el resto de tu workflow a Crear un workflow. El workflow queda en estado draft, y Flowker valida aquí la configuración del disparador. Un error de contrato responde FLK-0934.

Actívalo

Llama a Activar un workflow. La activación registra el path y el método. También resuelve lo que referencia el contrato. Un esquema XSD faltante responde FLK-0930 y un esquema OpenAPI faltante responde FLK-0931. Una operación que el documento no declara responde FLK-0932, y una operación sin cuerpo de solicitud responde FLK-0933.

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

Un solo workflow activo es dueño de un par de path y método dentro de tu tenant. Activar un segundo workflow sobre el mismo par responde FLK-0360. Desactivar un workflow libera sus rutas, así que puedes entregar un path a una versión nueva.

Paso 6: Llama a la ruta y confirma que funciona

Envía la llamada como la enviará quien llama:

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

Una ruta async nueva cuya ejecución no es terminal responde 202 con el comprobante:

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

Una ruta sync responde con el resultado de la ejecución, en la forma que selecciona su response_view. El estado que lleva depende de la vista y de cómo terminó la ejecución. Modo de respuesta síncrona tiene esas reglas. Tres señales te dicen que la ruta funcionó:

Una respuesta que inició una ejecución lleva X-Webhook-Workflow-ID y X-Webhook-Execution-ID, así que puedes ligar una llamada al workflow que alcanzó y a la ejecución que inició.
Obtener resultados de ejecución informa los resultados por paso y la salida final de ese executionId.
La entrada de la ejecución lleva un objeto _webhook con el método, el path y la dirección de quien llama. Úsalo para confirmar que el workflow vio la llamada que debía ver. Consulta Metadatos del webhook.

Una entrega repetida con la misma Idempotency-Key devuelve la ejecución original en lugar de iniciar otra. En una ruta async, una repetición terminal devuelve un comprobante HTTP 200 con idempotencyReplayed: true y el estado original. En una ruta sync, el estado y el cuerpo siguen a response_view y a cualquier responseStatusCode terminal: full y receipt incluyen metadatos de repetición, mientras que final_output y una respuesta passthrough directa no lo garantizan. Envía una clave nueva para ejecutar el workflow otra vez. Los cinco verbos tienen cada uno su propia página de referencia: POST, GET, PUT, PATCH y DELETE.

Cuando una llamada falla

Código	Cuándo ocurre	Qué hacer
`FLK-0934`	Guardas el workflow.	Compara el `data` del disparador con la tabla de campos del Paso 4. Revisa este código primero cuando un disparador de webhook no se guarda.
`FLK-0930` … `FLK-0933`	Activas el workflow.	Confirma el id del esquema y, para `openapi`, confirma que el path y el método de la operación existen en el documento y que la operación declara un cuerpo de solicitud.
`FLK-0360`	Activas el workflow.	Otro workflow activo es dueño de ese path y ese método. Elige otro path, o desactiva el otro workflow.
`FLK-0361`	Quien llama envía una solicitud.	Ninguna ruta responde a ese path y ese método. Confirma que el workflow está activo, y que quien llama usa el método que declara el disparador.
`FLK-0501`	Quien llama envía una solicitud.	El workflow se resolvió pero no está activo. Actívalo.
`FLK-0001`	Quien llama envía una solicitud.	El cuerpo de una ruta JSON no es JSON válido.
`XML_MALFORMED`	Quien llama envía una solicitud.	El cuerpo de una ruta XML no es XML bien formado. Las rutas XML responden con este valor en el elemento `<error><code>`; para eso no se devuelve ningún código `FLK-`.
`XML_VALIDATION_FAILED`	Quien llama envía una solicitud.	El cuerpo de una ruta `xsd` es XML bien formado pero no cumple con el documento XSD. El documento `<error>` nombra la línea y la columna que fallan.
`FLK-0935`	Quien llama envía una solicitud.	El cuerpo JSON de una ruta `openapi` no cumple con el cuerpo de solicitud de la operación fijada. El mensaje identifica el primer JSON Pointer que falla e incluye el detalle de validación cuando está disponible.
`FLK-0720`	Quien llama envía una solicitud.	Flowker no pudo validar el payload, así que rechazó la llamada. Confirma que el servicio de validación y el esquema referenciado están disponibles para tu despliegue.
`FLK-0363`	Quien llama envía una solicitud.	El cuerpo supera 1 MB. Envía menos en una sola llamada.

Después de que Flowker resuelve una ruta, los errores de una ruta JSON devuelven code, title y message, mientras que los errores de una ruta XML devuelven un documento <error>. La verificación de tamaño del cuerpo FLK-0363 corre antes de la resolución de la ruta, así que devuelve el envelope de error JSON para todas las solicitudes. Consulta la lista de errores de Flowker para ver todos los códigos y ambas formas.

Qué sigue

Guía de integración

Conecta el workflow a servicios externos, y lee las reglas completas de respuesta síncrona.

Guía de diseño de workflows

Construye el resto del grafo al que entra el disparador.

Resumen

Guías

Console

Operaciones

Configurar un disparador de webhook

Antes de empezar

Paso 1: Lee el contrato del disparador en el catálogo

Paso 2: Elige el contrato de entrada

Paso 3: Decide cómo responde el webhook

Paso 4: Escribe el nodo disparador

Paso 5: Activa el workflow

Paso 6: Llama a la ruta y confirma que funciona

Cuando una llamada falla

Qué sigue

Guía de integración

Guía de diseño de workflows

​Antes de empezar

​Paso 1: Lee el contrato del disparador en el catálogo

​Paso 2: Elige el contrato de entrada

​Paso 3: Decide cómo responde el webhook

​Paso 4: Escribe el nodo disparador

​Paso 5: Activa el workflow

​Paso 6: Llama a la ruta y confirma que funciona

​Cuando una llamada falla

​Qué sigue

Guía de integración

Guía de diseño de workflows

Antes de empezar

Paso 1: Lee el contrato del disparador en el catálogo

Paso 2: Elige el contrato de entrada

Paso 3: Decide cómo responde el webhook

Paso 4: Escribe el nodo disparador

Paso 5: Activa el workflow

Paso 6: Llama a la ruta y confirma que funciona

Cuando una llamada falla

Qué sigue