> ## 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 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 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](/es/reference/flowker/flowker-api-quick-start) 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](/es/flowker/integration-guide#proteger-un-webhook).
* Para el contrato `xsd`: un documento XSD en el registro. Súbelo con [Subir un esquema XSD](/es/reference/flowker/upload-xsd-schema) 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`](/es/flowker/flowker-environment-variables).
* Para el contrato `openapi`: un documento OpenAPI en el registro ([Subir un esquema OpenAPI](/es/reference/flowker/upload-openapi-schema), cubierto de principio a fin en [Conectar tu propia API](/es/flowker/connecting-your-own-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](/es/reference/flowker/derive-openapi-operation-schema) 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.
[Listar triggers del catálogo](/es/reference/flowker/list-catalog-triggers) devuelve cada trigger con su `id`, `name` y `version`. El id del trigger de webhook es `webhook`.
```bash theme={null}
curl -s http://localhost:4021/v1/catalog/triggers | jq .
```
[Obtener un trigger del catálogo](/es/reference/flowker/get-catalog-trigger) 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.
```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 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](/es/reference/flowker/get-execution-results). |
| `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](/es/flowker/integration-guide#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](/es/reference/flowker/upload-xsd-schema). |
| `openapi_schema_id` | Con `openapi` | El id que devolvió [Subir un esquema OpenAPI](/es/reference/flowker/upload-openapi-schema). |
| `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`.
```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 respuesta sync 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 barra final, así que `payments/received`, `/payments/received` y `payments/received/` registran la misma ruta.
## Paso 5: Activa el workflow
***
Envía el node junto con el resto de tu workflow a [Crear un workflow](/es/reference/flowker/create-workflow). El workflow queda en estado `draft` y Flowker valida aquí la configuración del trigger — un error de contrato responde `FLK-0934`.
Llama a [Activar un workflow](/es/reference/flowker/activate-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`.
```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 path y método dentro de tu tenant. Activar un segundo workflow sobre el mismo par responde `FLK-0360`. [Desactivar un workflow](/es/reference/flowker/deactivate-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:
```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` 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/flowker/integration-guide#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](/es/reference/flowker/get-execution-results) 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](/es/flowker/integration-guide#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](/es/reference/flowker/trigger-webhook), [GET](/es/reference/flowker/trigger-webhook-get), [PUT](/es/reference/flowker/trigger-webhook-put), [PATCH](/es/reference/flowker/trigger-webhook-patch) y [DELETE](/es/reference/flowker/trigger-webhook-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](#paso-4-escribe-el-node-trigger). 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 ``. |
| `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 `` 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 ``. Consulta la [lista de errores de Flowker](/es/reference/flowker/flowker-error-list) para todos los códigos y ambas formas.
## Qué sigue
***
Conecta el workflow con servicios externos y lee las reglas completas de respuesta síncrona.
Construye el resto del grafo al que entra el trigger.