Configurando um trigger de webhook

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 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.
Para o contrato xsd: um documento XSD no registro. Faça o upload com Enviar um schema XSD 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.
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 path e do método da operação cujo request body descreve o seu payload. Derivar o schema de uma operação 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.

Liste os triggers incluídos

Listar triggers do catálogo retorna cada trigger com seu id, name e version. O id do trigger de webhook é webhook.

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

Leia o schema do trigger de webhook

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

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.
`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.

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.
`openapi_schema_id`	Com `openapi`	O id retornado por Enviar um schema OpenAPI.
`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.

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

Crie o workflow

Envie o node junto com o resto do seu workflow para Criar um workflow. O workflow fica em status draft e o Flowker valida aqui a configuração do trigger — um erro de contrato responde FLK-0934.

Ative-o

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

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 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:

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:

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

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, 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 trigger com a tabela de campos do Passo 4. 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 `<error>`.
`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 `<error>` 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 <error>. Veja a lista de erros do Flowker para todos os códigos e as duas formas.

Próximos passos

Guia de integração

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

Guia de design de workflows

Construa o resto do grafo em que o trigger entra.

Visão geral

Guias

Console

Operações

Configurando um trigger de webhook

Antes de começar

Passo 1: Leia o contrato do trigger no catálogo

Passo 2: Escolha o contrato de entrada

Passo 3: Decida como o webhook responde

Passo 4: Escreva o node trigger

Passo 5: Ative o workflow

Passo 6: Chame a rota e confirme que funciona

Quando uma chamada falha

Próximos passos

Guia de integração

Guia de design de workflows

​Antes de começar

​Passo 1: Leia o contrato do trigger no catálogo

​Passo 2: Escolha o contrato de entrada

​Passo 3: Decida como o webhook responde

​Passo 4: Escreva o node trigger

​Passo 5: Ative o workflow

​Passo 6: Chame a rota e confirme que funciona

​Quando uma chamada falha

​Próximos passos

Guia de integração

Guia de design de workflows

Antes de começar

Passo 1: Leia o contrato do trigger no catálogo

Passo 2: Escolha o contrato de entrada

Passo 3: Decida como o webhook responde

Passo 4: Escreva o node trigger

Passo 5: Ative o workflow

Passo 6: Chame a rota e confirme que funciona

Quando uma chamada falha

Próximos passos