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

# Webhook

> Receba solicitações HTTP externas para iniciar ou retomar execuções dos seus workflows

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.

<Note>
  O nó Webhook está disponível tanto em **Tools** quanto em **Skills**. Só é permitido **um nó Webhook por canvas**.
</Note>

***

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

```bash theme={null}
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.

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

<Tip>
  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.
</Tip>

***

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

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

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

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

### Considerações para Skills

<AccordionGroup>
  <Accordion title="Novas execuções em Skills">
    Para iniciar uma nova execução de uma Skill 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 a Skill possa enviar mensagens ao usuário através do canal correspondente.

    ```bash theme={null}
    curl -X POST https://brain.jelou.ai/v1/webhook/{webhookId} \
      -H "Content-Type: application/json" \
      -d '{"phone": "+5511999999999", "evento": "lembrete"}'
    ```
  </Accordion>

  <Accordion title="Retomar execuções em Skills">
    Para retomar uma execução existente, só é necessário o `executionId`. O sistema já possui o contexto do usuário da execução original.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="Versionamento">
    O webhook sempre executa a **última versão publicada** da Skill. Se houver mais de um bot do mesmo canal conectado ao projeto, o mais recente é utilizado.
  </Accordion>

  <Accordion title="Herança em workflows filhos">
    Quando uma Skill filha herda webhooks de sua Skill pai, se a Skill filha receber um request, isso **sobrescreve** os dados do webhook do fluxo pai. Os dados de `$webhook` se propagam para execuções filhas (nós Skill internos).
  </Accordion>
</AccordionGroup>

***

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

<Warning>
  Em Skills, o teste do draft é feito através do **Skill Tester**. Os parâmetros do usuário configurados no Skill Tester também se aplicam ao invocar o webhook em modo de teste.
</Warning>

***

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

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

***

## Casos de uso comuns

<CardGroup cols={2}>
  <Card title="Notificações de pagamento" icon="credit-card">
    Receba confirmações de gateways como Stripe ou MercadoPago e retome o fluxo de compra.
  </Card>

  <Card title="Integrações CRM" icon="building">
    Dispare fluxos automatizados quando um registro é criado ou atualizado no seu CRM.
  </Card>

  <Card title="Eventos de e-commerce" icon="cart-shopping">
    Processe eventos como abandono de carrinho, envio de pedido ou devolução.
  </Card>

  <Card title="Automações IoT" icon="microchip">
    Receba dados de sensores ou dispositivos para disparar fluxos de alerta ou processamento.
  </Card>
</CardGroup>