Por que meu webhook não está disparando?

O que é um webhook (rápido)

É uma ponte automática: quando algo acontece numa ferramenta externa (por exemplo, um lead preenche um formulário), ela envia os dados para uma URL do BotConversa, que então executa ações sobre o contato (cadastrar, atualizar nome, etc.).

Causas comuns

• O webhook está em Modo Teste (não dispara ações reais).
• A URL está errada na ferramenta de origem (os dados nunca chegam).
• O formato dos dados não foi mapeado (o webhook recebe, mas não sabe o que fazer com cada campo).
• Você atingiu o limite de requisições da conta.

Como verificar cada uma

1. Webhook em Modo Teste — como checar

Modo Teste quer dizer que o webhook não está funcionando de verdade: ele só serve para capturar um exemplo de dados e montar o mapeamento antes de você ativar.

1. Abra o editor do webhook.
2. No canto superior direito, veja o toggle. Se aparecer "Modo Teste. Webhook não está funcionando", ele não vai executar ações reais.
3. Lembre-se: todo webhook recém-criado nasce em Modo Teste por padrão.

2. URL errada na ferramenta de origem — como checar

1. Copie a URL exata do webhook no BotConversa.
2. Confira se a ferramenta externa está enviando o POST para essa mesma URL, sem caracteres a mais ou a menos.
3. Se os dados não estão chegando, o problema costuma estar na origem (URL errada, integração desligada).

3. Dados não mapeados — como checar

1. No editor, olhe o painel Requisições (esquerda): você precisa ter ao menos uma requisição capturada (um exemplo de dados) para mapear.
2. No painel Ações (direita), confira se você apontou o campo do Telefone WhatsApp (com o DDI/código do país) e, se quiser, o Nome do contato.
3. Marque também a confirmação de consentimento do contato. Sem o mapeamento mínimo, o webhook não tem o que executar.

4. Limite de requisições atingido — como checar

1. Vá em Automação → Webhooks.
2. No canto superior direito, veja o indicador "Limite de requisições: X/25000" (X = quanto já foi usado). Esse contador soma as requisições de todos os webhooks da conta.
3. Se você chegou ao teto, novas requisições provavelmente são bloqueadas.

Como diagnosticar pelos logs

1. Em Automação → Webhooks, olhe as colunas Requisições do mês e Requisições totais do webhook. Se estão em zero, os dados não estão chegando (problema de URL/origem).
2. No editor do webhook, use Mostrar análises para detalhar as requisições recebidas.
3. Se as requisições estão chegando mas nada acontece nos contatos, o problema é de mapeamento ou de Modo Teste.

Como resolver

1. Saia do Modo Teste: depois de capturar um exemplo e mapear os campos, ative o webhook (desligue o Modo Teste).
2. Corrija a URL: garanta que a ferramenta de origem envia para a URL exata do webhook.
3. Complete o mapeamento: selecione a requisição capturada e mapeie Telefone (com DDI) e Nome; marque o consentimento.
4. Monitore o limite: acompanhe o contador de requisições e evite estourar o teto.

Quando chamar o suporte

• As requisições aparecem como recebidas, o webhook está ativo e mapeado, mas as ações não acontecem nos contatos.
• O contador de requisições não sobe mesmo com a ferramenta de origem confirmando envios.
• Você não sabe interpretar o que aparece em Mostrar análises.