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.

Só é permitido um nó Webhook por canvas.

URL do webhook

A URL é gerada pelo próprio nó. Abra-o no Studio e use Copiar URL: o identificador final é o ID do nó Webhook, não um identificador separado. As chamadas entram pelo gateway da Jelou. O nó gera duas URLs, conforme qual versão do workflow você queira executar. Produção — executa a última versão publicada do workflow:

curl -X POST "https://gateway.jelou.ai/workflows/v2/webhooks/skill/{workflowId}/{canal}/{nodeId}" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $JELOU_API_KEY"

Testes (draft) — executa o workflow como está no canvas agora, com as alterações que você ainda não publicou:

curl -X POST "https://gateway.jelou.ai/workflows/v2/webhooks/skill/{workflowId}/{canal}/test/{nodeId}" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $JELOU_API_KEY"

{canal} é o canal do workflow em minúsculas: whatsapp, web, instagram, facebook, slack, teams, twitter ou custom.

O gateway exige autenticação. Envie sua API key no header x-api-key em cada chamada ao webhook; sem esse header a resposta é 401 Unauthorized. Crie e gerencie a sua em Chaves API.

Já tem uma integração apontando para o host anterior, workflows.jelou.ai? Ela continua funcionando e não precisa migrar com urgência. A URL do gateway se aplica às integrações novas.

Copie sempre a URL do nó em vez de construí-la manualmente.

Os exemplos desta página usam a URL de produção. Para testar contra o draft, troque {nodeId} por test/{nodeId}.

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. Para iniciar uma execução nova é necessário o identificador do usuário. No exemplo ele vai como ?userId=; a outra forma está em Webhook em Workflows.

curl -X POST "https://gateway.jelou.ai/workflows/v2/webhooks/skill/{workflowId}/{canal}/{nodeId}?userId=%2B5511999999999" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $JELOU_API_KEY" \
  -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://gateway.jelou.ai/workflows/v2/webhooks/skill/{workflowId}/{canal}/{nodeId} \
  -H "Content-Type: application/json" \
  -H "x-api-key: $JELOU_API_KEY" \
  -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.

O método HTTP é obrigatório. Se publicar o nó sem ter selecionado um, toda requisição à URL será rejeitada. Selecione-o antes de publicar.

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.Você pode enviá-lo de duas formas:

No body: configure o campo ID do usuário no painel do nó com o caminho (dot notation) onde o identificador chega.
Como query param: acrescente ?userId= à URL, sem configurar nada no painel.

# ID no body, com o campo "ID do usuário" configurado como `phone`
curl -X POST https://gateway.jelou.ai/workflows/v2/webhooks/skill/{workflowId}/whatsapp/{nodeId} \
  -H "Content-Type: application/json" \
  -H "x-api-key: $JELOU_API_KEY" \
  -d '{"phone": "+5511999999999", "evento": "lembrete"}'

# ID como query param
curl -X POST "https://gateway.jelou.ai/workflows/v2/webhooks/skill/{workflowId}/whatsapp/{nodeId}?userId=%2B5511999999999" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $JELOU_API_KEY" \
  -d '{"evento": "lembrete"}'

Se o identificador não chegar por nenhuma das duas vias, o webhook responde com um erro indicando que falta o userId.

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 canal, 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 canal do mesmo tipo 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 que inclui o segmento /test antes do ID do nó:

curl -X POST "https://gateway.jelou.ai/workflows/v2/webhooks/skill/{workflowId}/{canal}/test/{nodeId}" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $JELOU_API_KEY"

A URL /test executa o draft atual do workflow, permitindo iterar sem afetar a versão publicada. Além disso, não exige o identificador do usuário: esses parâmetros vêm do Workflow Tester.

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.
As URLs anteriores continuam sendo atendidas, conforme indicado em URL do webhook.

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

Desenvolvedor

Jelou CLI

Mensagens Outbound

Gestão

Marketplace

Canais

Configuração

Faturamento

URL do webhook

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

​URL do webhook

​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

URL do webhook

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