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.
- Clique em Novo webhook.
- 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. - Marque os eventos, um a um, ou Todos os eventos.
- 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.testesó 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.
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.