Configurando um gatilho de webhook

Um gatilho de webhook é o ponto de entrada de um workflow que começa a partir de uma chamada HTTP de entrada. Você declara um caminho e um método no nó de gatilho. Quando você ativa o workflow, o Flowker serve esse caminho. Cada chamada nova aceita começa uma execução do workflow. Uma repetição com o mesmo Idempotency-Key retorna a execução existente. 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 Primeiros passos com o Flowker para o caminho de criar e ativar.
Com PLUGIN_AUTH_ENABLED=true (obrigatório em produção), conceda a permissão execute no recurso webhooks a cada sistema que você deixa chamar o caminho. Veja Protegendo um webhook. Um deploy fora de produção com a autenticação de plugin desabilitada usa um passthrough que não autoriza.
Para o contrato xsd: um documento XSD no registro. Envie ele com Enviar um schema XSD e guarde o id que ele retorna. Para exigir a validação XSD na entrada, configure o serviço de validação de XML por XSD_VALIDATOR_URL. Quando essa variável não está definida, o Flowker decodifica XML bem formado, mas pula a validação XSD.
Para o contrato openapi: um documento OpenAPI no registro (Enviar um schema OpenAPI, coberto de ponta a ponta em Conectando a sua própria API). 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 mostra esse corpo de requisição.

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.

Liste os gatilhos embutidos

Listar gatilhos do catálogo retorna cada gatilho com o id, o name e a version dele. O id do gatilho de webhook é webhook.

curl -s http://localhost:4021/v1/catalog/triggers | jq .

Leia o schema do gatilho de webhook

Obter um gatilho do catálogo 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.

curl -s http://localhost:4021/v1/catalog/triggers/webhook | 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. O validador atualmente também aceita format em xsd e openapi. Esses modos ignoram o campo e forçam XML ou JSON, respectivamente. Omita ele nesses casos para que a configuração não sugira que ele muda a rota. 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.

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 por esse serviço. 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. Configure esse serviço antes de colocar uma rota xsd na frente de quem chama e exige validação de schema.

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. 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 janela fechar antes, quem chama recebe o mesmo recibo `202` mais um header `Location` apontando para o endpoint de resultados.

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.

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.

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 e efetivo apenas com `open`: `"json"` ou `"xml"`. O validador atualmente aceita ele com `xsd` e `openapi`, onde é ignorado.
`xsd_schema_id`	Com `xsd`	O id que Enviar um schema XSD retornou.
`openapi_schema_id`	Com `openapi`	O id que Enviar um schema OpenAPI 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` e `X-Auth-Token`; 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

Uma declaração accepted_headers inválida falha com FLK-0957.

{
  "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"
  }
}

{
  "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"
  }
}

{
  "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"
  }
}

{
  "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"
  }
}

{
  "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

Crie o workflow

Envie o nó com o resto do seu workflow para Criar um workflow. O workflow chega no status draft, e o Flowker valida a configuração do gatilho aqui. Um erro de contrato responde FLK-0934.

Ative ele

Chame Ativar um workflow. 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.

curl -s -X POST http://localhost:4021/v1/workflows/019c96a0-0ac0-7de9-9f53-9cf842a2ee5a/activate | 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 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:

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 nova cuja execução não é terminal responde 202 com o recibo:

{
  "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 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 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.

Uma entrega repetida com o mesmo Idempotency-Key retorna a execução original em vez de começar outra. Em uma rota async, uma repetição terminal retorna um recibo HTTP 200 com idempotencyReplayed: true e o status original. Em uma rota sync, o status e o corpo seguem o response_view e qualquer responseStatusCode terminal: full e receipt incluem metadados de repetição, enquanto final_output e uma resposta passthrough direta não garantem isso. Envie uma chave nova para rodar o workflow de novo. Os cinco verbos têm cada um a própria página de referência: POST, GET, PUT, PATCH e DELETE.

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. 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-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 `<error><code>`; 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 `<error>` 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 serviço de validação e o schema referenciado estão disponíveis para o seu deploy.
`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 <error>. 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 para todos os códigos e os dois formatos.

O que vem depois

Guia de integração

Conecte o workflow a serviços externos e leia as regras completas de resposta síncrona.

Guia de desenho de workflows

Monte o resto do grafo em que o gatilho entra.

Visão geral

Guias

Console

Operações

Configurando um gatilho de webhook

Antes de começar

Etapa 1: Leia o contrato do gatilho no catálogo

Etapa 2: Escolha o contrato de entrada

Etapa 3: Decida como o webhook responde

Etapa 4: Escreva o nó de gatilho

Etapa 5: Ative o workflow

Etapa 6: Chame a rota e confirme que ela funciona

Quando uma chamada falha

O que vem depois

Guia de integração

Guia de desenho de workflows

​Antes de começar

​Etapa 1: Leia o contrato do gatilho no catálogo

​Etapa 2: Escolha o contrato de entrada

​Etapa 3: Decida como o webhook responde

​Etapa 4: Escreva o nó de gatilho

​Etapa 5: Ative o workflow

​Etapa 6: Chame a rota e confirme que ela funciona

​Quando uma chamada falha

​O que vem depois

Guia de integração

Guia de desenho de workflows

Antes de começar

Etapa 1: Leia o contrato do gatilho no catálogo

Etapa 2: Escolha o contrato de entrada

Etapa 3: Decida como o webhook responde

Etapa 4: Escreva o nó de gatilho

Etapa 5: Ative o workflow

Etapa 6: Chame a rota e confirme que ela funciona

Quando uma chamada falha

O que vem depois