Configurar un disparador de webhook

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

Un webhook trigger es el punto de entrada de un workflow que empieza con una llamada HTTP entrante. Declaras una ruta y un método en el nodo de trigger. Cuando activas el workflow, Flowker pasa a servir esa ruta. Cada llamada nueva aceptada inicia una ejecución del workflow. Una repetición con la misma Idempotency-Key devuelve, en cambio, la ejecución existente del mismo workflow.

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 Paso 4: Ejecuta el workflow para el recorrido de creación y activación.
• Concede el permiso execute sobre el recurso webhooks a cada sistema al que dejas llamar la ruta. Consulta Proteger un webhook. Una ruta con el contrato xsd también comprueba el permiso validate sobre el recurso xsd-schemas con el token del llamador.
• Para el contrato xsd: un documento XSD en el registro. Súbelo con Subir un esquema XSD y guarda el id que devuelve.
• 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.
• Para una suscripción de webhook de Streaming Hub: define su endpoint como Disparar un webhook desde Streaming Hub. Esa ruta inicia el mismo workflow y comprueba la firma del Hub en lugar de un bearer token. El deployment debe activarla, y el signing secret de la suscripción debe ser igual al que el deployment guarda para tu tenant. El ping de verificación del Hub responde 204 cuando se verifica su firma, y no corre ningún workflow. Flowker identifica cada entrega del Hub por su id de evento, así que, mientras exista la primera ejecución, una reentrega del mismo evento no ejecuta el workflow de nuevo.

​

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.

1. 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 https://your-flowker-host/v1/catalog/triggers \
     -H "Authorization: Bearer <token>" | jq .
   
2. 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 https://your-flowker-host/v1/catalog/triggers/webhook \
     -H "Authorization: Bearer <token>" | 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. Omite format en xsd y openapi. Un valor distinto de "xml" en xsd, o distinto de "json" en openapi, hace que el guardado falle con FLK-0934.

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. Un documento que no cumple se rechaza con XML_VALIDATION_FAILED. Flowker rechaza con FLK-0720 un veredicto en el que no puede confiar.

​

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 ejecución se detiene en una espera, o 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 passthrough, una ejecución que sigue en curso cuando se cierra la ventana responde 504 con el comprobante, y la ejecución continúa.

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: la respuesta del proveedor, retransmitida cuando la ejecución se completó, o la salida propia de un nodo set_output terminal. Una ejecución que falló responde HTTP 502 con status, errorMessage y errorClass, y nunca retransmite una respuesta de proveedor, ni siquiera un 4xx.

Una ejecución sync que falla responde HTTP 502 en todas las views. Mientras exista la primera ejecución, una repetición con el mismo Idempotency-Key, o una reentrega de Streaming Hub del mismo evento, responde el mismo 502 y no ejecuta el workflow de nuevo. 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. El último segmento puede ser un parámetro {name}, como en "orders/{orderId}". Consulta Terminar un path con un parámetro.
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 con open: "json" o "xml". Omítelo con xsd y openapi.
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, X-Auth-Token y X-Webhook-Signature; 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

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. Un path con una llave que no sea un último segmento {name}, o dos templates del mismo método bajo el mismo path padre en un workflow, falla con FLK-0963.

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

​

Terminar un path con un parámetro

Un path puede terminar en un segmento {name} después de al menos un segmento fijo. El nombre empieza con una letra y tiene letras, dígitos y guiones bajos. orders/{orderId} sirve orders/123 y orders/abc. El workflow lee el valor del último segmento, sin escape de URL, en _webhook.params.orderId. Un path exacto gana sobre un template. Consulta Metadatos del webhook.

​

Paso 5: Activa el workflow

---

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

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 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 https://your-flowker-host/v1/workflows/019c96a0-0ac0-7de9-9f53-9cf842a2ee5a/activate \
     -H "Authorization: Bearer <token>" | jq .
   

Un solo workflow es dueño de un par de path y método dentro de tu tenant, desde la primera vez que se activa hasta que lo eliminas. Activar un segundo workflow sobre el mismo par responde FLK-0360. Para un template, un workflow es dueño de cada método y path padre. Desactivar un workflow no libera sus rutas. Para entregar un path a una versión nueva, elimina primero el workflow anterior.

​

Paso 6: Llama a la ruta y confirma que funciona

---

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

curl -i -X POST https://your-flowker-host/v1/webhooks/payments/received \
  -H "Authorization: Bearer <token>" \
  -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, un replay terminal devuelve un recibo 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 los metadatos del replay, mientras que final_output y una respuesta passthrough directa no lo garantizan. Envía una clave nueva para ejecutar el workflow de nuevo. El replay dura mientras exista la primera ejecución: 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.

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 es dueño de ese path y ese método. Elige otro path, o elimina el workflow que es dueño de él.
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-0519	El llamador envía una solicitud.	El workflow tiene una lista allowedCallers y el llamador no está en ella. No se crea ninguna ejecución.
FLK-0511	El llamador envía una solicitud.	La Idempotency-Key ya se usó en un workflow distinto. Envía una clave nueva.
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 esquema referenciado existe en el registro. Si existe y la llamada sigue fallando, contacta al soporte de Lerian.
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.