Configurando webhooks

Antes de começar

• Tenha em mãos a ferramenta externa que vai enviar os dados (um formulário, um CRM, um sistema de pedidos).
• Garanta que você tem consentimento dos contatos para receber mensagens. É exigido ao configurar o webhook.

O que é um webhook: é um aviso automático que o BotConversa manda — ou recebe — quando algo acontece. Neste artigo, tratamos do webhook de entrada: a outra ferramenta avisa o BotConversa, e ele cria ou atualiza um contato. É diferente da chamada de saída, em que o seu fluxo é quem avisa o exterior (veja a seção no fim).

Passo a passo

Passo 1: Abra Automação e a aba Webhooks

No menu lateral, clique em Automação e selecione a aba Webhooks. No canto superior direito você verá o indicador de Limite de requisições (o teto de chamadas que sua conta aceita).

Passo 2: Crie o webhook

Clique em Criar, digite um Nome (ex.: "Leads do site") e confirme. O webhook aparece na lista com o status Modo Teste.

Passo 3: Abra o editor e copie a URL

Clique no Status ("Modo Teste") na linha do webhook para abrir o editor. Lá está a URL do webhook, com um botão de copiar. Essa URL é o endereço para onde a outra ferramenta vai enviar os dados.

Passo 4: Envie a URL para a outra ferramenta

Cole a URL copiada na ferramenta externa, no lugar onde ela pede o endereço de webhook (em formulários e CRMs costuma ficar em "Integrações" ou "Webhooks"). A partir daí, sempre que houver um novo registro, a ferramenta avisa o BotConversa.

Passo 5: Faça a ferramenta enviar um exemplo

Ainda em Modo Teste, faça a ferramenta enviar um registro de exemplo (preencha o formulário uma vez, por exemplo). Esse envio chega como uma Requisição dentro do editor e serve de modelo para o mapeamento.

Importante: em Modo Teste o webhook não dispara ações reais. Ele só captura o exemplo para você configurar com segurança.

Passo 6: Mapeie o conteúdo recebido

No painel Requisições, selecione a requisição de exemplo que chegou. No painel Ações, diga ao BotConversa qual campo recebido é o quê:

• Telefone WhatsApp — aponte o campo com o número. O código do país (DDI) deve vir junto; se não vier, informe manualmente.
• Criar/Atualizar Nome do Contato — aponte o campo com o nome. Se o contato ainda não existir, ele é cadastrado.
• Consentimento — marque a confirmação de que o contato autorizou receber mensagens.

Passo 7: Ative o webhook

Com o mapeamento pronto, desligue o Modo Teste pelo toggle no canto superior direito. O webhook passa a processar os dados reais que chegarem e a executar as ações configuradas.

Passo 8: Acompanhe pelos logs

Verifique se está tudo funcionando pelas colunas Requisições do mês e Requisições totais na lista. Dentro do editor, use Mostrar análises para ver mais detalhes das requisições recebidas.

Webhook de entrada x chamada de saída

São coisas diferentes:

• Webhook de entrada (este artigo): a ferramenta externa avisa o BotConversa. Útil para receber leads de fora e criar contatos.
• Chamada de saída: o seu fluxo é quem avisa o exterior, fazendo uma chamada HTTP para uma URL de outro sistema. Isso é feito pelo bloco Integração dentro do fluxo. Veja Entendendo os tipos de bloco.

Envio de mídia via webhook (URL pública com extensão)

O webhook de entrada também aceita enviar mídia para o contato logo após criá-lo/atualizá-lo. Para isso, o JSON recebido precisa trazer uma URL pública que termine com a extensão do arquivo:

• Imagem: .jpg, .jpeg, .png
• Vídeo: .mp4
• Áudio: .mp3, .ogg
• Documento: .pdf

Exemplo de URL aceita: https://meudominio.com/uploads/recibo-1234.pdf.

Cuidados:

• A URL precisa ser pública (acessível sem login).
• A extensão é obrigatória — sem ela, o BotConversa não detecta o tipo de mídia.
• Limites do WhatsApp se aplicam (ex.: imagem até 5 MB, documento até 100 MB; consulte os limites oficiais da Meta).
• Envios de mídia para contatos fora da janela de 24h só funcionam dentro de um Modelo de Mensagem (HSM) com mídia aprovada.