> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rovax.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Nó Webhook

> Receba requisições HTTP externas e use o payload como ponto de entrada do seu workflow na Timely.ai.

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

<Note>
  Salve o workflow pelo menos uma vez antes de tentar copiar a URL do webhook. A URL só é gerada após o primeiro salvamento.
</Note>

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

Use uma string aleatória longa como token — pelo menos 32 caracteres — e nunca exponha esse valor em logs ou interfaces públicas. O campo exibe o token mascarado por padrão; clique no ícone de olho para revelar temporariamente.

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

<Note>
  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**.
</Note>

Para testar o webhook:

1. Clique em **Iniciar Teste** — o sistema começa a escutar na URL do webhook por até 60 segundos.
2. Envie uma requisição de teste do sistema externo (ou use curl, Postman ou similar).
3. O payload capturado aparece em tempo real no painel, incluindo body, headers, query params e método.
4. 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:

```json theme={null}
{
  "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         |