> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.
# 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 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](/es/reference/products/flowker/flowker-api-quick-start) 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](/es/products/flowker/integration-guide#securing-a-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](/es/reference/products/flowker/upload-xsd-schema) 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`](/es/products/flowker/flowker-environment-variables). 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](/es/reference/products/flowker/upload-openapi-schema), cubierto de punta a punta en [Conectar tu propia API](/es/products/flowker/connecting-your-own-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](/es/reference/products/flowker/derive-openapi-operation-schema) 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.
[Listar disparadores del catálogo](/es/reference/products/flowker/list-catalog-triggers) devuelve cada disparador con su `id`, `name` y `version`. El id del disparador de webhook es `webhook`.
```bash theme={null}
curl -s http://localhost:4021/v1/catalog/triggers | jq .
```
[Obtener un disparador del catálogo](/es/reference/products/flowker/get-catalog-trigger) 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.
```bash theme={null}
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](/es/reference/products/flowker/get-execution-results). 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](/es/products/flowker/integration-guide#synchronous-response-mode).
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](/es/reference/products/flowker/upload-xsd-schema). |
| `openapi_schema_id` | Con `openapi` | El id que devolvió [Subir un esquema OpenAPI](/es/reference/products/flowker/upload-openapi-schema). |
| `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.
```json open JSON theme={null}
{
"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"
}
}
```
```json open XML theme={null}
{
"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"
}
}
```
```json xsd theme={null}
{
"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"
}
}
```
```json openapi theme={null}
{
"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"
}
}
```
```json sync response theme={null}
{
"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
***
Envía el nodo con el resto de tu workflow a [Crear un workflow](/es/reference/products/flowker/create-workflow). El workflow queda en estado `draft`, y Flowker valida aquí la configuración del disparador. Un error de contrato responde `FLK-0934`.
Llama a [Activar un workflow](/es/reference/products/flowker/activate-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`.
```bash theme={null}
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](/es/reference/products/flowker/deactivate-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:
```bash theme={null}
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:
```json theme={null}
{
"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](/es/products/flowker/integration-guide#synchronous-response-mode) 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](/es/reference/products/flowker/get-execution-results) 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](/es/products/flowker/integration-guide#webhook-metadata).
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](/es/reference/products/flowker/trigger-webhook), [GET](/es/reference/products/flowker/trigger-webhook-get), [PUT](/es/reference/products/flowker/trigger-webhook-put), [PATCH](/es/reference/products/flowker/trigger-webhook-patch) y [DELETE](/es/reference/products/flowker/trigger-webhook-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](#step-4-write-the-trigger-node). 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 ``; 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 `` 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 ``. 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](/es/reference/products/flowker/flowker-error-list) para ver todos los códigos y ambas formas.
## Qué sigue
***
Conecta el workflow a servicios externos, y lee las reglas completas de respuesta síncrona.
Construye el resto del grafo al que entra el disparador.