Configurar un trigger de webhook

Un trigger de webhook es el punto de entrada de un workflow que empieza con una llamada HTTP entrante. Declaras un path y un method en el node trigger. Cuando activas el workflow, Flowker atiende ese path y ejecuta el workflow en cada llamada que acepta. El input_contract del trigger decide qué payloads acepta Flowker y cómo los decodifica. Elígelo antes de escribir el node: es obligatorio y fija el formato del payload para toda la ruta.

Antes de empezar

Un workflow en estado draft. Un workflow activo queda bloqueado, así que agrega el trigger antes de activarlo. Consulta Primeros pasos con Flowker para el camino de creación y activación.
El permiso execute sobre el recurso webhooks para cada sistema al que permitas llamar al path. Consulta Proteger un webhook.
Para el contrato xsd: un documento XSD en el registro. Súbelo con Subir un esquema XSD y guarda el id que devuelve. Tu despliegue también necesita el servicio de validación XML contra el que valida el contrato — consulta XSD_VALIDATOR_URL.
Para el contrato openapi: un documento OpenAPI en el registro (Subir un esquema OpenAPI, cubierto de principio a fin en Conectar tu propia API). También necesitas el path y el método de la operación cuyo request body describe tu payload. Derivar el esquema de una operación te muestra ese request body.

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

Los triggers vienen incluidos. Los descubres en el catálogo y nunca creas uno.

Lista los triggers incluidos

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

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

Lee el esquema del trigger de webhook

Obtener un trigger del catálogo devuelve los mismos campos más schema — el JSON Schema contra el que Flowker valida tu node trigger. 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 que declares en `format`	Decodifica el cuerpo y no ejecuta validación de contrato.	`format` — `"json"` o `"xml"`
`xsd`	XML	Valida el documento contra el esquema XSD que referenciaste.	`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 del payload de la ruta. Una ruta xsd es XML y una ruta openapi es JSON. Una ruta open usa el format que declaras, y format pertenece solo a ese modo. Elige open cuando el payload de quien llama no tiene un contrato publicado, o cuando prefieres que el workflow decida qué es aceptable. Elige xsd cuando un partner envía XML definido por un documento XSD. Elige openapi cuando un partner envía JSON y 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. Una ruta xsd llega a su veredicto a través del servicio de validación XML que configura tu despliegue — un documento que no cumple el esquema se rechaza con XML_VALIDATION_FAILED, y un veredicto del que Flowker no puede fiarse, con FLK-0720. Configura ese servicio antes de poner una ruta xsd delante de quien llama.

Paso 3: Decide cómo responde el webhook

`response_mode`	Qué recibe quien llama
`async` (predeterminado)	HTTP `202` con el comprobante de ejecución, en cuanto la ejecución arranca. El workflow sigue en segundo plano y quien llama lee el resultado en Obtener resultados de ejecución.
`sync`	Flowker mantiene la conexión hasta que la ejecución llega a un estado terminal, hasta 15 segundos, y luego devuelve el resultado. Si la ventana se cierra antes, quien llama recibe el mismo comprobante `202` más un encabezado `Location` que apunta al endpoint de resultados.

En una ruta sync, response_view define la forma del cuerpo:

`response_view`	Cuerpo
`full` (predeterminado)	El envelope completo de la ejecución: `executionId`, `workflowId`, `status`, `stepResults` y `finalOutput`.
`final_output`	Solo la salida de negocio final de la ejecución.
`receipt`	El comprobante enjuto: `executionId`, `workflowId`, `status` y `startedAt`.
`passthrough`	La forma que implica el step terminal — una respuesta del provider retransmitida, o la salida propia de un node `set_output` terminal.

response_view no tiene efecto en una ruta async. Para las reglas completas de passthrough y para el override responseStatusCode, consulta Modo de respuesta síncrona.

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

Paso 4: Escribe el node trigger

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

Campo	Cuándo lo defines	Valor
`triggerType`	Siempre	`"webhook"`.
`path`	Siempre	El path a atender, por ejemplo `"payments/received"`. Lleva tantos segmentos como necesites.
`method`	Siempre	El método que responde la ruta: `GET`, `POST`, `PUT`, `PATCH` o `DELETE`, en mayúsculas.
`input_contract`	Siempre	`"open"`, `"xsd"` u `"openapi"`.
`format`	Con `open`	`"json"` o `"xml"`.
`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, por ejemplo `"/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"`.

La configuración del trigger es un contrato cerrado. Guardar un workflow cuyo trigger de webhook omite path, method o input_contract, olvida un campo que su modo input_contract exige, nombra el id de esquema o un campo de operación de otro modo, o lleva una clave o un valor que el esquema no acepta falla con FLK-0934.

{
  "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 barra final, así que payments/received, /payments/received y payments/received/ registran la misma ruta.

Paso 5: Activa el workflow

Crea el workflow

Envía el node junto con el resto de tu workflow a Crear un workflow. El workflow queda en estado draft y Flowker valida aquí la configuración del trigger — 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 ausente responde FLK-0930 y un esquema OpenAPI ausente responde FLK-0931. Una operación que el documento no declara responde FLK-0932, y una operación sin request body 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 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 nueva versión.

Paso 6: Llama a la ruta y confirma que funciona

Envía la llamada tal 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 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 guarda 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 vincular una llamada con el workflow que alcanzó y la ejecución que inició.
Obtener resultados de ejecución informa los resultados por step 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 correcta. Consulta Metadatos del webhook.

Una entrega repetida que lleva el mismo Idempotency-Key devuelve la ejecución original en lugar de iniciar una segunda, y su cuerpo lleva idempotencyReplayed: true con el status original. Envía una clave nueva para ejecutar el workflow otra vez. Los cinco verbos tienen 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 trigger con la tabla de campos del Paso 4. Revisa este código primero cuando un trigger 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 request body.
`FLK-0360`	Activas el workflow.	Otro workflow activo es dueño de ese path y 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 método. Confirma que el workflow está activo y que quien llama usa el método que declara el trigger.
`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.
`FLK-0364`	Quien llama envía una solicitud.	El cuerpo de una ruta XML no es XML bien formado. Una ruta XML lo reporta como `XML_MALFORMED` en el documento `<error>`.
`XML_VALIDATION_FAILED`	Quien llama envía una solicitud.	El cuerpo de una ruta `xsd` es XML bien formado pero no cumple 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 el request body de la operación fijada. El mensaje nombra el campo que falla.
`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.

Una ruta JSON devuelve code, title y message. Una ruta XML devuelve un documento <error>. Consulta la lista de errores de Flowker para todos los códigos y ambas formas.

Qué sigue

Guía de integración

Conecta el workflow con 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 trigger.

Resumen

Guías

Console

Operaciones

Configurar un trigger de webhook

Antes de empezar

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

Paso 2: Elige el contrato de entrada

Paso 3: Decide cómo responde el webhook

Paso 4: Escribe el node trigger

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 trigger en el catálogo

​Paso 2: Elige el contrato de entrada

​Paso 3: Decide cómo responde el webhook

​Paso 4: Escribe el node trigger

​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 trigger en el catálogo

Paso 2: Elige el contrato de entrada

Paso 3: Decide cómo responde el webhook

Paso 4: Escribe el node trigger

Paso 5: Activa el workflow

Paso 6: Llama a la ruta y confirma que funciona

Cuando una llamada falla

Qué sigue