> ## 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 trigger de webhook > Inicie um workflow do Flowker a partir de uma chamada HTTP recebida. Escolha o contrato do payload, decida como o webhook responde e confirme que a rota atende quem chama. Um trigger de webhook é o ponto de entrada de um workflow que começa com uma chamada HTTP recebida. Você declara um path e um method no node trigger. Quando você ativa o workflow, o Flowker atende esse path e executa o workflow em cada chamada que aceita. O `input_contract` do trigger decide quais payloads o Flowker aceita e como os decodifica. Escolha-o antes de escrever o node: ele é obrigatório e fixa o formato do payload para toda a rota. ## Antes de começar *** * Um workflow em status `draft`. Um workflow ativo fica bloqueado, portanto adicione o trigger antes de ativá-lo. Veja [Primeiros passos com o Flowker](/pt/reference/flowker/flowker-api-quick-start) para o caminho de criação e ativação. * A permissão `execute` sobre o recurso `webhooks` para cada sistema que você autoriza a chamar o path. Veja [Protegendo um webhook](/pt/flowker/integration-guide#protegendo-um-webhook). * Para o contrato `xsd`: um documento XSD no registro. Faça o upload com [Enviar um schema XSD](/pt/reference/flowker/upload-xsd-schema) e guarde o id retornado. A sua implantação também precisa do serviço de validação XML contra o qual o contrato valida — veja [`XSD_VALIDATOR_URL`](/pt/flowker/flowker-environment-variables). * Para o contrato `openapi`: um documento OpenAPI no registro ([Enviar um schema OpenAPI](/pt/reference/flowker/upload-openapi-schema), coberto de ponta a ponta em [Conectando a sua própria API](/pt/flowker/connecting-your-own-api)). Você também precisa do path e do método da operação cujo request body descreve o seu payload. [Derivar o schema de uma operação](/pt/reference/flowker/derive-openapi-operation-schema) mostra esse request body. ## Passo 1: Leia o contrato do trigger no catálogo *** Os triggers já vêm incluídos. Você os descobre no catálogo e nunca cria um. [Listar triggers do catálogo](/pt/reference/flowker/list-catalog-triggers) retorna cada trigger com seu `id`, `name` e `version`. O id do trigger de webhook é `webhook`. ```bash theme={null} curl -s http://localhost:4021/v1/catalog/triggers | jq . ``` [Obter um trigger do catálogo](/pt/reference/flowker/get-catalog-trigger) retorna os mesmos campos mais `schema` — o JSON Schema contra o qual o Flowker valida o seu node trigger. Leia-o quando quiser a lista de campos direto da instância em execução. ```bash theme={null} curl -s http://localhost:4021/v1/catalog/triggers/webhook | jq -r '.schema' | jq . ``` ## Passo 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 o que você declara em `format` | Decodifica o corpo e não executa validação de contrato. | `format` — `"json"` ou `"xml"` | | `xsd` | XML | Valida o documento contra o schema XSD que você referenciou. | `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 do payload da rota. Uma rota `xsd` é XML e uma rota `openapi` é JSON. Uma rota `open` usa o `format` que você declara, e o `format` pertence apenas a esse modo. Escolha `open` quando o payload de quem chama não tem contrato publicado, ou quando você prefere que o próprio workflow decida o que é aceitável. Escolha `xsd` quando um parceiro envia XML definido por um documento XSD. Escolha `openapi` quando um parceiro envia JSON e você tem o documento OpenAPI que o descreve. Uma rota `openapi` nunca aceita um payload sem verificação: quando o Flowker não consegue chegar a um veredito, ele rejeita a chamada com `FLK-0720`, e o workflow nunca vê esse payload. Uma rota `xsd` chega ao seu veredito por meio do serviço de validação XML que a sua implantação configura — um documento que não está em conformidade é rejeitado com `XML_VALIDATION_FAILED`, e um veredito em que o Flowker não pode confiar, com `FLK-0720`. Configure esse serviço antes de colocar uma rota `xsd` na frente de quem chama. ## Passo 3: Decida como o webhook responde *** | `response_mode` | O que quem chama recebe | | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `async` (padrão) | HTTP `202` com o comprovante de execução, assim que a execução começa. O workflow continua em segundo plano e quem chama lê o resultado em [Obter resultados da execução](/pt/reference/flowker/get-execution-results). | | `sync` | O Flowker mantém a conexão até a execução alcançar um estado terminal, por até 15 segundos, e então retorna o resultado. Se a janela fechar antes, quem chama recebe o mesmo comprovante `202` mais um cabeçalho `Location` apontando para o endpoint de resultados. | Em uma rota `sync`, o `response_view` define a forma do corpo: | `response_view` | Corpo | | --------------- | ------------------------------------------------------------------------------------------------------------------------------- | | `full` (padrão) | O envelope completo da execução: `executionId`, `workflowId`, `status`, `stepResults` e `finalOutput`. | | `final_output` | Apenas a saída de negócio final da execução. | | `receipt` | O comprovante enxuto: `executionId`, `workflowId`, `status` e `startedAt`. | | `passthrough` | A forma que o step terminal implica — uma resposta do provider retransmitida, ou a saída do próprio node `set_output` terminal. | O `response_view` não tem efeito em uma rota `async`. Para as regras completas de `passthrough` e para o override `responseStatusCode`, veja [Modo de resposta síncrona](/pt/flowker/integration-guide#modo-de-resposta-síncrona). Escolha `async` quando quem chama só precisa saber que o evento chegou. Escolha `sync` quando precisa da resposta na mesma chamada — por exemplo, um parceiro que espera uma decisão na mesma conexão. ## Passo 4: Escreva o node trigger *** O trigger de webhook é um node com `type: "trigger"` e estes campos em seu `data`: | Campo | Quando você define | Valor | | ------------------- | ------------------ | --------------------------------------------------------------------------------------------------------------------------------- | | `triggerType` | Sempre | `"webhook"`. | | `path` | Sempre | O path a atender, por exemplo `"payments/received"`. Ele aceita quantos segmentos você precisar. | | `method` | Sempre | O método que a rota responde: `GET`, `POST`, `PUT`, `PATCH` ou `DELETE`, em maiúsculas. | | `input_contract` | Sempre | `"open"`, `"xsd"` ou `"openapi"`. | | `format` | Com `open` | `"json"` ou `"xml"`. | | `xsd_schema_id` | Com `xsd` | O id retornado por [Enviar um schema XSD](/pt/reference/flowker/upload-xsd-schema). | | `openapi_schema_id` | Com `openapi` | O id retornado por [Enviar um schema OpenAPI](/pt/reference/flowker/upload-openapi-schema). | | `operation_path` | Com `openapi` | O path da operação exatamente como o documento OpenAPI o escreve, por exemplo `"/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"`. | A configuração do trigger é um contrato fechado. Salvar um workflow cujo trigger de webhook omite `path`, `method` ou `input_contract`, esquece um campo que o seu modo `input_contract` exige, nomeia o id de schema ou um campo de operação de outro modo, ou carrega uma chave ou um valor que o schema não aceita falha com `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 resposta 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" } } ``` O Flowker registra o path com uma barra inicial e sem barra final, então `payments/received`, `/payments/received` e `payments/received/` registram a mesma rota. ## Passo 5: Ative o workflow *** Envie o node junto com o resto do seu workflow para [Criar um workflow](/pt/reference/flowker/create-workflow). O workflow fica em status `draft` e o Flowker valida aqui a configuração do trigger — um erro de contrato responde `FLK-0934`. Chame [Ativar um workflow](/pt/reference/flowker/activate-workflow). A ativação registra o path 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 request body responde `FLK-0933`. ```bash theme={null} curl -s -X POST http://localhost:4021/v1/workflows/019c96a0-0ac0-7de9-9f53-9cf842a2ee5a/activate | jq . ``` Um único workflow ativo é dono de um par path e método dentro do seu tenant. Ativar um segundo workflow sobre o mesmo par responde `FLK-0360`. [Desativar um workflow](/pt/reference/flowker/deactivate-workflow) libera as suas rotas, então você pode entregar um path a uma nova versão. ## Passo 6: Chame a rota e confirme que funciona *** Envie a chamada como quem chama vai enviar: ```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 }' ``` Uma rota `async` responde `202` com o comprovante: ```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, na forma que o seu `response_view` seleciona. O status que ela carrega depende da visão e de como a execução terminou — [Modo de resposta síncrona](/pt/flowker/integration-guide#modo-de-resposta-síncrona) guarda essas regras. Três sinais indicam que a rota funcionou: * Uma resposta que iniciou uma execução carrega `X-Webhook-Workflow-ID` e `X-Webhook-Execution-ID`, então você liga uma chamada ao workflow que ela alcançou e à execução que iniciou. * [Obter resultados da execução](/pt/reference/flowker/get-execution-results) informa os resultados por step e a saída final daquele `executionId`. * A entrada da execução carrega um objeto `_webhook` com o método, o path e o endereço de quem chama. Use-o para confirmar que o workflow viu a chamada correta. Veja [Metadados do webhook](/pt/flowker/integration-guide#metadados-do-webhook). Uma entrega repetida que carrega o mesmo `Idempotency-Key` retorna a execução original em vez de iniciar uma segunda, e o seu corpo carrega `idempotencyReplayed: true` com o `status` original. Envie uma chave nova para executar o workflow de novo. Os cinco verbos têm a sua própria página de referência: [POST](/pt/reference/flowker/trigger-webhook), [GET](/pt/reference/flowker/trigger-webhook-get), [PUT](/pt/reference/flowker/trigger-webhook-put), [PATCH](/pt/reference/flowker/trigger-webhook-patch) e [DELETE](/pt/reference/flowker/trigger-webhook-delete). ## Quando uma chamada falha *** | Código | Quando acontece | O que fazer | | ----------------------- | -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `FLK-0934` | Você salva o workflow. | Compare o `data` do trigger com a tabela de campos do [Passo 4](#passo-4-escreva-o-node-trigger). Verifique este código primeiro quando um trigger de webhook não salva. | | `FLK-0930` … `FLK-0933` | Você ativa o workflow. | Confirme o id do schema e, para `openapi`, confirme que o path e o método da operação existem no documento e que a operação declara um request body. | | `FLK-0360` | Você ativa o workflow. | Outro workflow ativo é dono desse path e método. Escolha outro path ou desative o outro workflow. | | `FLK-0361` | Quem chama envia uma requisição. | Nenhuma rota responde a esse path e método. Confirme que o workflow está ativo e que quem chama usa o método declarado pelo trigger. | | `FLK-0501` | Quem chama envia uma requisição. | O workflow foi resolvido mas não está ativo. Ative-o. | | `FLK-0001` | Quem chama envia uma requisição. | O corpo de uma rota JSON não é um JSON válido. | | `FLK-0364` | Quem chama envia uma requisição. | O corpo de uma rota XML não é um XML bem formado. Uma rota XML reporta isso como `XML_MALFORMED` no documento ``. | | `XML_VALIDATION_FAILED` | Quem chama envia uma requisição. | O corpo de uma rota `xsd` é um XML bem formado, mas não está em conformidade com o documento XSD. O documento `` nomeia a linha e a coluna que falham. | | `FLK-0935` | Quem chama envia uma requisição. | O corpo JSON de uma rota `openapi` não está em conformidade com o request body da operação fixada. A mensagem nomeia o campo que falha. | | `FLK-0720` | Quem chama envia uma requisição. | O Flowker não conseguiu validar o payload, então rejeitou a chamada. Confirme que o serviço de validação e o schema referenciado estão disponíveis para a sua implantação. | | `FLK-0363` | Quem chama envia uma requisição. | O corpo passa de 1 MB. Envie menos em uma única chamada. | Uma rota JSON retorna `code`, `title` e `message`. Uma rota XML retorna um documento ``. Veja a [lista de erros do Flowker](/pt/reference/flowker/flowker-error-list) para todos os códigos e as duas formas. ## Próximos passos *** Conecte o workflow a serviços externos e leia as regras completas de resposta síncrona. Construa o resto do grafo em que o trigger entra.