Webhook

O nó Webhook transforma seu workflow em um endpoint HTTP acessível a partir de qualquer sistema externo. Permite dois fluxos principais: iniciar novas execuções e retomar execuções existentes — tudo por meio de uma simples chamada HTTP. Pense neste nó como a porta de entrada do seu workflow: sistemas externos batem na porta (enviam um request HTTP) e seu fluxo decide o que fazer com o que trazem.

O nó Webhook está disponível tanto em Tools quanto em Workflows. Só é permitido um nó Webhook por canvas.

Modos de operação

O nó Webhook opera em dois modos, determinados automaticamente pela presença do executionId:

Iniciar nova execução

Quando o request não inclui um executionId, o webhook cria uma nova execução do workflow do zero. Caso de uso: Um sistema externo (CRM, ERP, gateway de pagamento) precisa disparar um processo automatizado no Jelou.

curl -X POST https://brain.jelou.ai/v1/webhook/{webhookId} \
  -H "Content-Type: application/json" \
  -d '{"evento": "novo_pedido", "cliente": "12345"}'

Retomar execução existente

Quando o request inclui um executionId, o webhook retoma uma execução que estava pausada esperando uma resposta externa. Caso de uso: Um gateway de pagamento notifica que o pagamento foi processado, e o fluxo deve continuar de onde parou.

curl -X POST https://brain.jelou.ai/v1/webhook/{webhookId} \
  -H "Content-Type: application/json" \
  -d '{"executionId": "abc-123", "status": "paid"}'

O executionId pode ser enviado no body (usando o path configurado em dot notation) ou como query param executionId. Isso permite usar métodos HTTP como GET que não possuem body.

Configuração

Nome da variável

Define o nome sob o qual os dados do webhook serão armazenados dentro da variável $webhook. Os dados recebidos pelo request ficarão disponíveis em $webhook.<nomeVariável>. Por exemplo, se definir meuWebhook, poderá acessar o body via {{$webhook.meuWebhook.body}}, os headers via {{$webhook.meuWebhook.headers}}, etc.

Método HTTP

Selecione os métodos HTTP que o webhook aceita. Suporta GET, POST, PUT, PATCH e DELETE.

Para métodos sem body (como GET), o executionId para retomar deve ser enviado como query param: ?executionId=abc-123.

Retomar múltiplas vezes (oneTimeOnly)

Por padrão, uma execução pode ser retomada mais de uma vez pelo webhook. Se precisar restringir isso — por exemplo, em integrações de pagamento onde uma confirmação só deve ser processada uma vez — você pode ativar a opção “Retomar apenas uma vez” nas configurações avançadas.

Configuração	Comportamento
oneTimeOnly desativado (padrão)	O webhook pode retomar a mesma execução múltiplas vezes
oneTimeOnly ativado	O webhook só retoma a execução uma vez; tentativas posteriores são ignoradas

Variável `$webhook`

Quando um request chega ao nó Webhook, todas as informações do request ficam disponíveis através da variável $webhook. Funciona de maneira similar a $memory e $context.

Propriedade	Descrição	Exemplo
`$webhook.<nomeVariável>.body`	Corpo do request HTTP	`{"evento": "pagamento_sucesso", "valor": 50}`
`$webhook.<nomeVariável>.headers`	Headers enviados no request	`{"content-type": "application/json"}`
`$webhook.<nomeVariável>.query`	Query params da URL	`{"ref": "campanha-123"}`
`$webhook.<nomeVariável>.method`	Método HTTP utilizado	`POST`
`$webhook.<nomeVariável>.mode`	Modo da execução	`new` ou `resume`
`$webhook.<nomeVariável>.executionId`	ID da execução atual	`exec-abc-123`
`$webhook.<nomeVariável>.isNewExecution`	Indica se é uma execução nova	`true` ou `false`

Exemplo de uso no fluxo

Assumindo que você definiu meuWebhook como nome da variável, pode usar as propriedades em qualquer nó posterior:

# Em um nó Condicional
{{$webhook.meuWebhook.body.evento}} == "pagamento_sucesso"

# Em um nó Texto
O pagamento de {{$webhook.meuWebhook.body.valor}} foi processado com sucesso.

# Em um nó API
Authorization: {{$webhook.meuWebhook.headers.authorization}}

Webhook em Workflows

O nó Webhook está disponível em Workflows, permitindo que fluxos conversacionais sejam disparados ou retomados por eventos externos.

Considerações para Workflows

Novas execuções em Workflows

Para iniciar uma nova execução de um Workflow via webhook, o request deve incluir o identificador do usuário (por exemplo, o número de telefone no WhatsApp). Isso é necessário para que o Workflow possa enviar mensagens ao usuário através do canal correspondente.

curl -X POST https://brain.jelou.ai/v1/webhook/{webhookId} \
  -H "Content-Type: application/json" \
  -d '{"phone": "+5511999999999", "evento": "lembrete"}'

Retomar execuções em Workflows

Para retomar uma execução existente, só é necessário o executionId. O sistema já possui o contexto do usuário da execução original.

Restrições de plataforma

Em plataformas como WhatsApp, se não houver uma sessão ativa (janela de 24 horas) entre o usuário e o bot, o webhook não poderá enviar mensagens diretamente. Nesses casos, você pode usar um nó HSM dentro do fluxo para enviar um template aprovado que reabre a janela conversacional.

Versionamento

O webhook sempre executa a última versão publicada do Workflow. Se houver mais de um bot do mesmo canal conectado ao projeto, o mais recente é utilizado.

Herança em workflows filhos

Quando um Workflow filho herda webhooks de seu Workflow pai, se o Workflow filho receber um request, isso sobrescreve os dados do webhook do fluxo pai. Os dados de $webhook se propagam para execuções filhas (nós Workflow internos).

Testes (Draft)

Para testar o webhook durante o desenvolvimento (antes de publicar), o nó gera uma URL de testes com o sufixo /test:

# URL de produção
https://brain.jelou.ai/v1/webhook/{webhookId}

# URL de testes (draft)
https://brain.jelou.ai/v1/webhook/{webhookId}/test

A URL /test executa o draft atual do workflow, permitindo iterar sem afetar a versão publicada.

Em Workflows, o teste do draft é feito através do Workflow Tester. Os parâmetros do usuário configurados no Workflow Tester também se aplicam ao invocar o webhook em modo de teste.

Retrocompatibilidade

Os webhooks criados antes desta atualização continuam funcionando sem alterações. As melhorias se aplicam apenas daqui para frente:

Webhooks existentes mantêm sua configuração legacy, incluindo o campo “variável” que armazenava os dados em $context.
Webhooks novos sempre armazenam as informações na nova entidade $webhook, oferecendo uma estrutura mais rica e consistente.

Para webhooks legacy que tinham uma variável de contexto configurada, o componente de configuração de variável continuará sendo exibido por retrocompatibilidade. Em webhooks novos, este campo não aparece já que os dados são sempre armazenados em $webhook.

Casos de uso comuns

Notificações de pagamento

Receba confirmações de gateways como Stripe ou MercadoPago e retome o fluxo de compra.

Integrações CRM

Dispare fluxos automatizados quando um registro é criado ou atualizado no seu CRM.

Eventos de e-commerce

Processe eventos como abandono de carrinho, envio de pedido ou devolução.

Automações IoT

Receba dados de sensores ou dispositivos para disparar fluxos de alerta ou processamento.

Primeiros Passos

Agentes de IA

Nós

Variáveis

Observabilidade nos Workflows

Mensagens Outbound

Gestão

Marketplace

Canais

Configuração

Faturamento

Modos de operação

Iniciar nova execução

Retomar execução existente

Configuração

Nome da variável

Método HTTP

Retomar múltiplas vezes (oneTimeOnly)

Variável `$webhook`

Exemplo de uso no fluxo

Webhook em Workflows

Considerações para Workflows

Testes (Draft)

Retrocompatibilidade

Casos de uso comuns

Notificações de pagamento

Integrações CRM

Eventos de e-commerce

Automações IoT

​Modos de operação

​Iniciar nova execução

​Retomar execução existente

​Configuração

​Nome da variável

​Método HTTP

​Retomar múltiplas vezes (oneTimeOnly)

​Variável $webhook

​Exemplo de uso no fluxo

​Webhook em Workflows

​Considerações para Workflows

​Testes (Draft)

​Retrocompatibilidade

​Casos de uso comuns

Notificações de pagamento

Integrações CRM

Eventos de e-commerce

Automações IoT

Modos de operação

Iniciar nova execução

Retomar execução existente

Configuração

Nome da variável

Método HTTP

Retomar múltiplas vezes (oneTimeOnly)

Variável `$webhook`

Exemplo de uso no fluxo

Webhook em Workflows

Considerações para Workflows

Testes (Draft)

Retrocompatibilidade

Casos de uso comuns