> ## 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. # Configurando um gatilho de webhook > Comece um workflow do Flowker a partir de uma chamada HTTP de entrada. Escolha o contrato de payload, decida como o webhook responde e confirme que a rota atende quem chama. Um webhook trigger é o ponto de entrada de um workflow que começa com uma chamada HTTP de entrada. Você declara um caminho e um método no nó de trigger. Quando você ativa o workflow, o Flowker passa a servir esse caminho. Cada chamada nova aceita inicia uma execução do workflow. Uma repetição com a mesma `Idempotency-Key` devolve, em vez disso, a execução existente do mesmo workflow. O `input_contract` opcional decide quais payloads o Flowker aceita e como ele os decodifica. Defina esse campo de forma explícita em nós novos: ele fixa o formato de payload da rota inteira. Nós mais antigos que o omitem continuam válidos. O Flowker deriva `xsd` quando eles trazem um schema XSD e formato XML. Caso contrário, o Flowker os trata como `open` com JSON como formato padrão. ## Antes de começar *** * Um workflow em status `draft`. Um workflow ativo fica travado, então adicione o gatilho antes de ativar. Veja [Passo 4: Rode o workflow](https://docs.lerian.studio/pt/products/flowker/integration-guide.md#step-4-run-the-workflow) para o caminho de criar e ativar. * Conceda a permissão `execute` no recurso `webhooks` a cada sistema que você deixa chamar o caminho. Veja [Protegendo um webhook](https://docs.lerian.studio/pt/products/flowker/integration-guide.md#securing-a-webhook). Uma rota com o contrato `xsd` também confere a permissão `validate` no recurso `xsd-schemas` com o token do chamador. * Para o contrato `xsd`: um documento XSD no registro. Envie ele com [Enviar um schema XSD](https://docs.lerian.studio/pt/reference/products/flowker/upload-xsd-schema.md) e guarde o id que ele retorna. * Para o contrato `openapi`: um documento OpenAPI no registro ([Enviar um schema OpenAPI](https://docs.lerian.studio/pt/reference/products/flowker/upload-openapi-schema.md), coberto de ponta a ponta em [Conectando a sua própria API](https://docs.lerian.studio/pt/products/flowker/connecting-your-own-api.md)). Você também precisa do caminho e do método da operação cujo corpo de requisição descreve o seu payload. [Derivar o schema de uma operação](https://docs.lerian.studio/pt/reference/products/flowker/derive-openapi-operation-schema.md) mostra esse corpo de requisição. * Para uma assinatura de webhook do Streaming Hub: defina o `endpoint` dela como [Disparar um webhook a partir do Streaming Hub](https://docs.lerian.studio/pt/reference/products/flowker/trigger-webhook-from-streaming-hub.md). Essa rota inicia o mesmo workflow e confere a assinatura do Hub em vez de um bearer token. O deployment precisa ligá-la, e o signing secret da assinatura precisa ser igual ao que o deployment guarda para o seu tenant. O ping de verificação do Hub responde `204` quando a assinatura dele é verificada, e nenhum workflow roda. ## Etapa 1: Leia o contrato do gatilho no catálogo *** Os gatilhos são embutidos. Você descobre eles no catálogo e nunca cria um. **1. Liste os gatilhos embutidos** [Listar gatilhos do catálogo](https://docs.lerian.studio/pt/reference/products/flowker/list-catalog-triggers.md) retorna cada gatilho com o `id`, o `name` e a `version` dele. O id do gatilho de webhook é `webhook`. ```bash theme={null} curl -s https://your-flowker-host/v1/catalog/triggers \ -H "Authorization: Bearer " | jq . ``` **2. Leia o schema do gatilho de webhook** [Obter um gatilho do catálogo](https://docs.lerian.studio/pt/reference/products/flowker/get-catalog-trigger.md) retorna os mesmos campos mais `schema`, o JSON Schema contra o qual o Flowker valida o seu nó de gatilho. Leia esse campo quando você quiser a lista de campos da instância em execução. ```bash theme={null} curl -s https://your-flowker-host/v1/catalog/triggers/webhook \ -H "Authorization: Bearer " | jq -r '.schema' | jq . ``` ## Etapa 2: Escolha o contrato de entrada *** | Modo | O que a rota aceita | O que o Flowker faz com o payload | Campos que o modo exige | | - | - | - | - | | `open` | JSON ou XML, conforme você declara em `format` | Decodifica o corpo e não roda validação de contrato. | `format`: `"json"` ou `"xml"` | | `xsd` | XML | Com a validação XSD configurada, valida o documento contra o schema XSD que você referenciou. Sem ela, o Flowker decodifica XML bem formado, mas pula a validação XSD. | `xsd_schema_id` | | `openapi` | JSON | Valida o payload contra exatamente uma operação do documento OpenAPI que você referenciou, e rejeita um payload que não está em conformidade. | `openapi_schema_id`, `operation_path`, `operation_method` | O modo fixa o formato de payload da rota. Uma rota `xsd` é XML e uma rota `openapi` é JSON. Uma rota `open` usa o `format` que você declara. Omita `format` em `xsd` e `openapi`. Um valor diferente de `"xml"` em `xsd`, ou diferente de `"json"` em `openapi`, faz o salvamento falhar com `FLK-0934`. Escolha `open` quando o payload de quem chama não tem contrato publicado, ou quando você quer que o próprio workflow decida o que é aceitável. Quando um parceiro envia XML que um documento XSD define, escolha `xsd`. Escolha `openapi` quando um parceiro envia JSON e você tem o documento OpenAPI que o descreve. > [!NOTE] > > Uma rota `openapi` nunca aceita um payload não verificado: quando o Flowker não consegue chegar a um veredito, ele rejeita a chamada com `FLK-0720`, e o workflow nunca vê esse payload. Quando a validação XSD está configurada, uma rota `xsd` chega ao veredito dela. Um documento que não está em conformidade é rejeitado com `XML_VALIDATION_FAILED`. O Flowker rejeita com `FLK-0720` um veredito em que não pode confiar. ## Etapa 3: Decida como o webhook responde *** | `response_mode` | O que quem chama recebe | | - | - | | `async` (padrão) | Para uma execução nova e não terminal, HTTP `202` com o recibo da execução assim que ela começa. O workflow continua em segundo plano, e quem chama lê o resultado em [Obter resultados de uma execução](https://docs.lerian.studio/pt/reference/products/flowker/get-execution-results.md). Se a execução resolvida já está terminal, inclusive em uma repetição com `Idempotency-Key`, o Flowker retorna o recibo com HTTP `200` e metadados de repetição. | | `sync` | O Flowker segura a conexão até a execução chegar a um estado terminal, por até 15 segundos, depois retorna o resultado. Se a execução parar numa espera, ou a janela fechar antes, quem chama recebe o mesmo recibo `202` mais um header `Location` apontando para o endpoint de resultados. Numa rota `passthrough`, uma execução ainda em andamento quando a janela fecha responde `504` com o envelope do Flowker, e a execução continua. | Em uma rota `sync`, o `response_view` define o formato do corpo: | `response_view` | Corpo | | - | - | | `full` (padrão) | O envelope completo de resultados da execução: `executionId`, `workflowId`, `status`, `stepResults`, `finalOutput` quando disponível, `startedAt`, os opcionais `completedAt` e `inputData`, mais metadados de repetição de idempotência quando se aplicam. | | `final_output` | Para uma execução concluída, apenas o mapa final de saída de negócio (`{}` quando ausente). Para uma execução que falhou, um objeto de falha com `status: "failed"` e, quando disponíveis, `errorMessage` e `errorClass`. | | `receipt` | O recibo enxuto: `executionId`, `workflowId`, `status` e `startedAt`. | | `passthrough` | O formato que a etapa terminal implica: uma resposta de provedor repassada, ou a saída do próprio nó `set_output` terminal. Quando a execução falhou e a última etapa não capturou resposta de provedor, a resposta é o envelope `full` com HTTP `502`, mesmo que um nó `set_output` anterior tenha definido um `responseStatusCode`. | O `response_view` é inerte em uma rota `async`. Para as regras completas de `passthrough` e para a sobrescrita com `responseStatusCode`, veja [Modo de resposta síncrona](https://docs.lerian.studio/pt/products/flowker/integration-guide.md#synchronous-response-mode). > [!TIP] > > Escolha `async` quando quem chama precisa apenas saber que o evento chegou. Escolha `sync` quando quem chama precisa da resposta na mesma chamada (um parceiro que espera uma decisão na mesma conexão, por exemplo). ## Etapa 4: Escreva o nó de gatilho *** O gatilho de webhook é um nó com `type: "trigger"` e estes campos no `data` dele: | Campo | Quando você define | Valor | | - | - | - | | `triggerType` | Sempre | `"webhook"`. | | `path` | Sempre | O caminho a servir, como `"payments/received"`. Ele leva quantos segmentos você precisar. | | `method` | Sempre | O método que a rota responde: `GET`, `POST`, `PUT`, `PATCH` ou `DELETE`, em maiúsculas. | | `input_contract` | Opcional | `"open"`, `"xsd"` ou `"openapi"`. Defina de forma explícita em nós novos. Quando omitido, valem as regras legadas. | | `format` | Com `open` | Obrigatório com `open`: `"json"` ou `"xml"`. Omita ele com `xsd` e `openapi`. | | `xsd_schema_id` | Com `xsd` | O id que [Enviar um schema XSD](https://docs.lerian.studio/pt/reference/products/flowker/upload-xsd-schema.md) retornou. | | `openapi_schema_id` | Com `openapi` | O id que [Enviar um schema OpenAPI](https://docs.lerian.studio/pt/reference/products/flowker/upload-openapi-schema.md) retornou. | | `operation_path` | Com `openapi` | O caminho da operação como o documento OpenAPI escreve, como `"/orders"`. O Flowker faz a correspondência exata. | | `operation_method` | Com `openapi` | O método da operação: `GET`, `POST`, `PUT`, `PATCH` ou `DELETE`. | | `response_mode` | Opcional | `"async"` (padrão) ou `"sync"`. | | `response_view` | Opcional | `"full"` (padrão), `"final_output"`, `"receipt"` ou `"passthrough"`. | | `accepted_headers` | Opcional | Até 50 nomes extras de header de requisição para persistir em `_webhook.headers`, em todos os modos de contrato. Os nomes devem ser únicos sem diferenciar maiúsculas de minúsculas; cada um deve ser um nome de header HTTP não vazio, com no máximo 256 caracteres. A lista de bloqueio fixa rejeita `Authorization`, `Proxy-Authorization`, `Cookie`, `Set-Cookie`, `X-API-Key`, `X-Auth-Token` e `X-Webhook-Signature`; ela não detecta credenciais em outros headers. Nunca libere outro nome que carregue segredo, como `X-Amz-Security-Token`. | A configuração do gatilho é um contrato fechado. Um salvamento falha com `FLK-0934` quando o gatilho de webhook: * omite `path` ou `method` * não tem um campo que o modo `input_contract` selecionado exige * nomeia o id de schema ou o campo de operação de outro modo * leva uma chave ou um valor que o schema rejeita Um nome em `accepted_headers` que não é um nome de header válido, repete outro nome ou está na lista de bloqueio falha com `FLK-0957`. ```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" } } ``` O Flowker registra o caminho com uma barra inicial e sem barra final, então `payments/received`, `/payments/received` e `payments/received/` registram todos a mesma rota. ## Etapa 5: Ative o workflow *** **1. Crie o workflow** Envie o nó com o resto do seu workflow para [Criar um workflow](https://docs.lerian.studio/pt/reference/products/flowker/create-workflow.md). O workflow chega no status `draft`, e o Flowker valida a configuração do gatilho aqui. Um erro de contrato responde `FLK-0934`. **2. Ative ele** Chame [Ativar um workflow](https://docs.lerian.studio/pt/reference/products/flowker/activate-workflow.md). A ativação registra o caminho e o método. Ela também resolve o que o contrato referencia. Um schema XSD ausente responde `FLK-0930` e um schema OpenAPI ausente responde `FLK-0931`. Uma operação que o documento não declara responde `FLK-0932`, e uma operação sem corpo de requisição responde `FLK-0933`. ```bash theme={null} curl -s -X POST https://your-flowker-host/v1/workflows/019c96a0-0ac0-7de9-9f53-9cf842a2ee5a/activate \ -H "Authorization: Bearer " | jq . ``` Um workflow ativo é dono de um par de caminho e método dentro do seu tenant. Ativar um segundo workflow no mesmo par responde `FLK-0360`. [Desativar um workflow](https://docs.lerian.studio/pt/reference/products/flowker/deactivate-workflow.md) libera as rotas dele, então você pode passar um caminho para uma versão nova. ## Etapa 6: Chame a rota e confirme que ela funciona *** Envie a chamada do jeito que quem chama vai enviar: ```bash theme={null} curl -i -X POST https://your-flowker-host/v1/webhooks/payments/received \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -H "Idempotency-Key: 7f3e1a2b-4c5d-6e7f-8a9b-0c1d2e3f4a5b" \ -d '{ "transactionId": "txn-123", "amount": 1500.00 }' ``` Uma rota `async` nova cuja execução não é terminal responde `202` com o recibo: ```json theme={null} { "executionId": "019c96a0-10ce-75fc-a273-dc799079a99c", "workflowId": "019c96a0-0ac0-7de9-9f53-9cf842a2ee5a", "status": "running", "startedAt": "2026-03-18T14:35:00Z" } ``` Uma rota `sync` responde com o resultado da execução, no formato que o `response_view` dela seleciona. O status que ela leva depende da view e de como a execução terminou. [Modo de resposta síncrona](https://docs.lerian.studio/pt/products/flowker/integration-guide.md#synchronous-response-mode) tem essas regras. Três sinais dizem que a rota funcionou: * Uma resposta que começou uma execução leva `X-Webhook-Workflow-ID` e `X-Webhook-Execution-ID`, então você pode ligar uma chamada ao workflow que ela alcançou e à execução que ela começou. * [Obter resultados de uma execução](https://docs.lerian.studio/pt/reference/products/flowker/get-execution-results.md) informa os resultados das etapas e a saída final desse `executionId`. * A entrada da execução leva um objeto `_webhook` com o método, o caminho e o endereço de quem chamou. Use ele para confirmar que o workflow viu a chamada que devia ver. Veja [Metadados do webhook](https://docs.lerian.studio/pt/products/flowker/integration-guide.md#webhook-metadata). Uma entrega repetida com a mesma `Idempotency-Key` devolve a execução original em vez de iniciar outra. Em uma rota `async`, um replay terminal devolve um recibo HTTP `200` com `idempotencyReplayed: true` e o status original. Em uma rota `sync`, o status e o corpo seguem `response_view` e qualquer `responseStatusCode` terminal: `full` e `receipt` incluem os metadados do replay, enquanto `final_output` e uma resposta `passthrough` direta não garantem isso. Envie uma nova chave para executar o workflow de novo. O replay dura enquanto a primeira execução existir: o Flowker pode apagar uma execução finalizada só de leitura depois da [janela de retenção](https://docs.lerian.studio/pt/reference/products/flowker/get-execution-retention.md), e a mesma chave então inicia uma nova execução. Uma chave que você já usou em um workflow diferente responde `409` com `FLK-0511`. Os cinco verbos têm cada um a própria página de referência: [POST](https://docs.lerian.studio/pt/reference/products/flowker/trigger-webhook.md), [GET](https://docs.lerian.studio/pt/reference/products/flowker/trigger-webhook-get.md), [PUT](https://docs.lerian.studio/pt/reference/products/flowker/trigger-webhook-put.md), [PATCH](https://docs.lerian.studio/pt/reference/products/flowker/trigger-webhook-patch.md) e [DELETE](https://docs.lerian.studio/pt/reference/products/flowker/trigger-webhook-delete.md). ## Quando uma chamada falha *** | Código | Quando acontece | O que fazer | | - | - | - | | `FLK-0934` | Você salva o workflow. | Compare o `data` do gatilho com a tabela de campos da [Etapa 4](#step-4-write-the-trigger-node). Verifique este código primeiro quando um gatilho de webhook não salva. | | `FLK-0930` … `FLK-0933` | Você ativa o workflow. | Confirme o id do schema e, para `openapi`, confirme que o caminho e o método da operação existem no documento e que a operação declara um corpo de requisição. | | `FLK-0360` | Você ativa o workflow. | Outro workflow ativo é dono desse caminho e método. Escolha outro caminho ou desative o outro workflow. | | `FLK-0361` | Quem chama envia uma requisição. | Nenhuma rota responde nesse caminho e método. Confirme que o workflow está ativo e que quem chama usa o método que o gatilho declara. | | `FLK-0501` | Quem chama envia uma requisição. | O workflow foi resolvido, mas não está ativo. Ative ele. | | `FLK-0519` | O chamador envia uma requisição. | O workflow tem uma lista `allowedCallers` e o chamador não está nela. Nenhuma execução é criada. | | `FLK-0511` | O chamador envia uma requisição. | A `Idempotency-Key` já foi usada em um workflow diferente. Envie uma nova chave. | | `FLK-0001` | Quem chama envia uma requisição. | O corpo de uma rota JSON não é JSON válido. | | `XML_MALFORMED` | Quem chama envia uma requisição. | O corpo de uma rota XML não é XML bem formado. As rotas XML respondem com este valor no elemento ``; nenhum código `FLK-` é retornado para ele. | | `XML_VALIDATION_FAILED` | Quem chama envia uma requisição. | O corpo de uma rota `xsd` é XML bem formado, mas não está em conformidade com o documento XSD. O documento `` nomeia a linha e a coluna que falharam. | | `FLK-0935` | Quem chama envia uma requisição. | O corpo JSON de uma rota `openapi` não está em conformidade com o corpo de requisição da operação fixada. A mensagem identifica o primeiro JSON Pointer que falhou e inclui o detalhe da validação quando disponível. | | `FLK-0720` | Quem chama envia uma requisição. | O Flowker não conseguiu validar o payload, então rejeitou a chamada. Confirme que o schema referenciado existe no registro. Se existir e a chamada continuar falhando, entre em contato com o suporte da Lerian. | | `FLK-0363` | Quem chama envia uma requisição. | O corpo passa de 1 MB. Envie menos em uma chamada. | Depois que o Flowker resolve uma rota, os erros de rota JSON retornam `code`, `title` e `message`, enquanto os erros de rota XML retornam um documento ``. A verificação de tamanho de corpo do `FLK-0363` roda antes da resolução de rota, então ela retorna o envelope de erro JSON para todas as requisições. Veja a [lista de erros do Flowker](https://docs.lerian.studio/pt/reference/products/flowker/flowker-error-list.md) para todos os códigos e os dois formatos. ## O que vem depois *** > [card] [Guia de integração](https://docs.lerian.studio/pt/products/flowker/integration-guide.md) > > Conecte o workflow a serviços externos e leia as regras completas de resposta síncrona. > [card] [Guia de desenho de workflows](https://docs.lerian.studio/pt/products/flowker/workflow-design-guide.md) > > Monte o resto do grafo em que o gatilho entra. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.