# Webhooks de saída: receba os eventos do Bot no Make, n8n, Zapier ou no seu servidor

> Como cadastrar uma URL HTTPS e receber um POST assinado quando um lead entra ou sai, um convite quebra, um número cai, uma campanha fica sem grupo aberto ou um envio falha.

- URL: https://botdoafiliado.com/docs/api/webhooks/
- Publicado em: 2026-09-16
- Atualizado em: 2026-10-21
- Índice da documentação para IA: https://botdoafiliado.com/llms.txt

Um webhook de saída é uma URL sua que o Bot chama, com um `POST` em JSON, toda vez que acontece algo que você assinou. Serve para automações no Make, n8n e Zapier, ou para o seu próprio servidor.

## Cadastrar

O cartão **Webhooks** fica em **Organização**: no menu **Conta e organização** (rodapé do menu lateral), abra **Organização e membros**. O administrador chega pela busca (**Ctrl+K** → **Ir para Organização**). Veja [Organização](/docs/comecando/organizacao/).

1. Clique em **Novo webhook**.
2. Em **URL (https)**, cole o endereço. Só `https://` público: porta, IP, usuário e senha na URL e endereços internos não são aceitos.
3. Marque os eventos, um a um, ou **Todos os eventos**.
4. Clique em **Cadastrar**.

Cada organização pode ter até 5 webhooks; o cartão mostra quantos estão em uso. Só dono e administrador criam, editam, testam e apagam. Sem o módulo Conexão IA e API, o cartão mostra **Webhooks fazem parte do acesso à API**.

Na criação o Bot mostra o **secret uma única vez**, com **Copiar** e **Já guardei**. Guarde-o: é com ele que você confere a assinatura. Se perder, use **Gerar outro segredo**: o novo também aparece uma vez só.

## Gerenciar

Cada webhook mostra a URL, os eventos, o último HTTP e um selo de estado: **Ativo**, **Pausado**, falhas seguidas ou **Desativado por falhas**. O interruptor **Webhook ativo** pausa e religa. Os botões:

- **Últimas entregas**: abre a tabela das últimas 20 entregas.
- **Testar**: manda um `webhook.teste` só para aquele webhook e mostra o resultado.
- **Editar**: troca a URL e os eventos; **Salvar** ou **Cancelar**.
- **Gerar outro segredo**: troca o secret.
- **Apagar**: pede confirmação em **Apagar de vez?** → **Sim, apagar**.

## Eventos

| Evento | Quando dispara |
|---|---|
| `lead.entrou` | alguém entrou num grupo acompanhado (Telegram ou WhatsApp) |
| `lead.saiu` | alguém saiu ou foi removido |
| `grupo.convite_invalido` | o link de convite do grupo parou de funcionar |
| `grupo.suspenso` | o WhatsApp suspendeu o grupo |
| `grupo.recuperado` | o grupo voltou a operar |
| `numero.caiu` | um número do WhatsApp desconectou |
| `numero.voltou` | o número reconectou |
| `campanha.sem_grupo_aberto` | a campanha não tem grupo com vaga para receber quem clicou |
| `campanha.pausada` | a trava de segurança pausou a campanha: o mesmo conteúdo chegou 10 vezes em 10 minutos, sinal de laço entre chats |
| `envio.falhou` | um envio da fila do WhatsApp esgotou as tentativas |
| `oferta.clicada` | uma pessoa clicou numa oferta sua (link curto ou página de cópia); robôs e prévias de link não entram |
| `venda.atribuida` | uma venda casou com um clique seu ou com o código do grupo; venda com mais de 7 dias não sai |
| `venda.estornada` | a loja cancelou uma venda que já tinha saído para este webhook |
| `lead.email_confirmado` | alguém confirmou o e-mail pelo código no porteiro de entrada; o e-mail não vai no evento |
| `lead.ficou_30d` | alguém completou 30 dias no grupo sem sair, em grupo que o bot acompanha |

Assinar `*` recebe todos, inclusive os que forem criados depois. O botão **Testar** manda um `webhook.teste` só para aquele webhook.

## O que chega

```
POST https://sua-url
content-type: application/json
x-bot-event: lead.entrou
x-bot-delivery: whd_9f3c…
x-bot-timestamp: 1789900000
x-bot-signature: sha256=…

{"id":"whd_9f3c…","evento":"lead.entrou","workspace_id":"7","ocorrido_em":"2026-09-16T12:00:00.000Z","dados":{"grupo_id":"…","campanha_id":"…"}}
```

Responda `2xx` em até 10 segundos e processe depois. Redirecionamentos não são seguidos: cadastre a URL final. A mesma entrega pode chegar mais de uma vez se a sua resposta se perder na rede; use o `x-bot-delivery` para não processar em dobro (em preparação: o mesmo fato passa a ter sempre o mesmo `x-bot-delivery`). Entradas e saídas trazem apenas identificadores internos, nunca telefone.

## Conferir a assinatura

`x-bot-signature` é `sha256=` seguido do HMAC-SHA256, em hexadecimal, do texto `timestamp + "." + corpo cru`, usando o secret do webhook. O timestamp é o do cabeçalho `x-bot-timestamp` e muda a cada tentativa.

```js
import crypto from 'node:crypto';
const ts = req.get('x-bot-timestamp');
const esperado = 'sha256=' + crypto.createHmac('sha256', SECRET).update(`${ts}.${corpoCru}`).digest('hex');
const ok = crypto.timingSafeEqual(Buffer.from(esperado), Buffer.from(req.get('x-bot-signature') ?? ''));
```

No Make, n8n e Zapier o módulo "Webhook" recebe o corpo direto; a assinatura é opcional lá.

## Reentregas e pausa

| Resposta | O que o Bot faz |
|---|---|
| `2xx` | entrega concluída |
| `410 Gone` | desativa o webhook na hora |
| outro status, redirecionamento, timeout ou erro de rede | tenta de novo em 1 min, 5 min, 30 min e 2 h; a quinta tentativa é a última |
| 20 falhas seguidas | pausa o webhook e avisa o dono uma vez |
| venda cancelada antes de a entrega sair | a `venda.atribuida` não é enviada |

Religar o webhook no painel zera a contagem. Em **Últimas entregas**, cada linha mostra **Evento**, **Status**, **Tentativas**, **Resposta**, **Quando** e **Próxima tentativa**. O corpo enviado não aparece na tela.

Os avisos de queda do webhook (**Webhook desativado por falhas**) e os canais em que cada aviso operacional sai pelo webhook se escolhem em [Notificações](/docs/whatsapp/incidentes-e-alertas/).

## Perguntas frequentes

### Preciso de qual plano para usar webhooks?

Do módulo Conexão IA e API, o mesmo que libera as chaves de API e o MCP.

### O Bot reenvia se o meu servidor estiver fora do ar?

Sim. Reenvia em 1 min, 5 min, 30 min e 2 h; na quinta tentativa desiste daquela entrega. Vinte falhas seguidas pausam o webhook e avisam o dono.

### Como sei que o POST veio mesmo do Bot?

Pelo cabeçalho x-bot-signature, um HMAC-SHA256 do timestamp e do corpo com o secret que só aparece na criação.