Configurar un trigger de webhook

Inicia un workflow de Flowker desde una llamada HTTP entrante. Elige el contrato del payload, decide cómo responde el webhook y confirma que la ruta atiende a quien llama.

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. Cada llamada nueva aceptada inicia una ejecución del workflow; una repetición con el mismo Idempotency-Key devuelve la ejecución existente.

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.
• Con PLUGIN_AUTH_ENABLED=true — obligatorio en producción — concede el permiso execute sobre el recurso webhooks a cada sistema al que permitas llamar al path. Consulta Proteger un webhook. Un despliegue no productivo con autenticación de plugin deshabilitada usa un passthrough no autorizador.
• Para el contrato xsd: un documento XSD en el registro. Súbelo con Subir un esquema XSD y guarda el id que devuelve. Para aplicar la validación de entrada contra XSD, configura el servicio de validación XML mediante XSD_VALIDATOR_URL. Si no está configurado, 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 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.

1. 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 .
   
2. 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	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 del 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 también acepta actualmente format en xsd y openapi, pero esos modos lo ignoran y fuerzan XML o JSON respectivamente; omítelo ahí para no insinuar que cambia la ruta.

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. 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 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 que requiera la aplicación del esquema.

​

Paso 3: Decide cómo responde el webhook

---

response_mode	Qué recibe quien llama
async (predeterminado)	Para una ejecución nueva que no haya terminado, HTTP 202 con el comprobante en cuanto arranca. El workflow sigue en segundo plano y quien llama lee el resultado en Obtener resultados de ejecución. Si la ejecución resuelta ya terminó, 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 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 resultados de ejecución: executionId, workflowId, status, stepResults, finalOutput cuando esté disponible, startedAt, completedAt e inputData opcionales, además de los metadatos de repetición de idempotencia cuando correspondan.
final_output	Para una ejecución completada, solo el mapa de salida final del negocio ({} cuando no exista). Para una ejecución fallida, un objeto de error con status: "failed" y, cuando estén disponibles, errorMessage y errorClass.
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	Obligatorio y efectivo solo con open: "json" o "xml". El validador también lo acepta actualmente 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, 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 rechaza falla con FLK-0934.

open JSON

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

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

---

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

2. 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 nueva cuya ejecución no terminó 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 con el mismo 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 response_view y cualquier responseStatusCode terminal: full y receipt incluyen metadatos de repetición, mientras que final_output y una respuesta passthrough directa no los garantizan. 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.
XML_MALFORMED	Quien llama envía una solicitud.	El cuerpo de una ruta XML no es XML bien formado. Este es el valor de <error><code> que recibe quien llama; Flowker lo asigna desde el centinela interno FLK-0364.
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 identifica el primer puntero JSON 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 de una ruta XML devuelven un documento <error>. La comprobación de tamaño del cuerpo FLK-0363 se ejecuta antes de resolver la ruta, por lo que devuelve el envelope de error JSON para cualquier solicitud. 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.