Como Funciona
O nó Webhook gera um endpoint HTTP dedicado ao seu workflow. Quando um sistema externo — um e-commerce, um formulário, um ERP ou qualquer serviço — envia uma requisição para essa URL, a Timely valida a chamada e inicia a execução imediatamente.
O payload completo da requisição fica disponível para todos os nós seguintes via {{ $trigger }}. Isso inclui o corpo da requisição ($trigger.body), os headers enviados ($trigger.headers), os parâmetros de query string ($trigger.query) e o método HTTP utilizado ($trigger.method).
O nó opera em dois modos de resposta distintos. No modo immediate, o endpoint responde ao chamador assim que recebe a requisição, com um body fixo que você define — o workflow continua executando em paralelo sem bloquear a chamada. No modo node, a requisição fica suspensa até o fluxo atingir um nó Retornar Resposta, que define o status code e o corpo da resposta de forma dinâmica com base nos dados processados.
Salve o workflow pelo menos uma vez antes de tentar copiar a URL do webhook. A URL só é gerada após o primeiro salvamento.
Opções de Configuração
| Campo | Descrição |
|---|
| URL gerada | Endpoint exclusivo do workflow — copie e envie ao sistema externo |
| Método HTTP | GET, POST, PUT, PATCH ou DELETE — padrão POST |
| Autenticação | none ou bearer — controla validação do header Authorization |
| Token Bearer | Segredo usado para validar chamadas quando autenticação está ativa |
| Origens CORS | Domínios autorizados a chamar o webhook via browser — vazio aceita * |
| Modo de resposta | immediate (resposta fixa imediata) ou node (aguarda nó de resposta) |
Opções de Autenticação
Nenhuma
Quando definida como Nenhuma, o endpoint aceita qualquer requisição sem validar credenciais. Use apenas para integrações internas, redes privadas ou casos em que a segurança é garantida por outro mecanismo — como um IP allowlist no sistema chamador.
Requisições sem autenticação são adequadas para callbacks entre serviços dentro de uma mesma infraestrutura controlada, onde expor o endpoint publicamente sem proteção não representa risco.
Bearer Authentication
Quando definida como Bearer Token, a Timely valida o header Authorization em cada requisição recebida. Requisições que não incluam o header ou que apresentem um token diferente do configurado recebem 401 Unauthorized automaticamente, sem acionar a execução do workflow.
| Campo | Detalhe |
|---|
| Header esperado | Authorization: Bearer {seu-token-secreto} |
| Comportamento sem token | Retorna 401 Unauthorized e bloqueia a execução |
Modo de Teste do Nó
O painel do nó Webhook oferece um modo de teste integrado que permite capturar uma requisição real antes de publicar o workflow.
O modo de teste fica disponível apenas após salvar o workflow. Clique em Salvar para gerar a URL e habilitar o botão Iniciar Teste.
- Clique em Iniciar Teste — o sistema começa a escutar na URL do webhook por até 60 segundos.
- Envie uma requisição de teste do sistema externo (ou use curl, Postman ou similar).
- O payload capturado aparece em tempo real no painel, incluindo body, headers, query params e método.
- Clique em Fixar Output para usar os dados reais como valores de exemplo ao configurar os nós seguintes.
Exemplo de payload capturado após o teste:
{
"body": {
"evento": "pedido.criado",
"pedido_id": "ORD-5521",
"cliente_id": "C-881"
},
"headers": {
"content-type": "application/json",
"authorization": "Bearer meu-token"
},
"query": {},
"method": "POST"
}
Comportamento de Resposta
| Modo | Comportamento |
|---|
immediate | Responde ao chamador imediatamente com o body fixo configurado; o workflow continua em segundo plano |
node | Mantém a conexão aberta até o nó Retornar Resposta ser alcançado; timeout de 30000ms |
Casos de Uso Comuns
| Cenário | Configuração recomendada |
|---|
| Notificação de pagamento aprovado | POST com Bearer Token, modo immediate |
| Consulta síncrona de dados via API | POST com Bearer Token, modo node com Retornar Resposta |
Boas Práticas
- Sempre configure Bearer Token em endpoints expostos à internet — nunca deixe webhooks públicos sem autenticação
- Use o modo
node apenas quando o sistema chamador esperar a resposta de forma síncrona
- Adicione um nó Definir Variável logo após o trigger para extrair e renomear os campos do payload
- Valide o campo
$trigger.method em fluxos que aceitam mais de um método HTTP
- Documente a URL e o token do webhook em um local seguro — a URL não muda após a criação, mas o token pode ser rotacionado recriando o campo
Resumo
| Capacidade | Detalhe |
|---|
| Métodos suportados | GET, POST, PUT, PATCH, DELETE |
| Autenticação | Nenhuma ou Bearer Token |
| Modos de resposta | immediate ou node (timeout 30000ms) |
| Payload disponível | $trigger.body, $trigger.headers, $trigger.query, $trigger.method |
| Teste integrado | Captura requisição real e permite fixar output para configuração |
