--- title: "Configurando webhooks" url: https://ajuda.botconversa.com.br/aula/configurando-webhooks section: "Criando automações" date_modified: 2026-09-07T17:57:37.789013+00:00 language: pt-BR --- # Configurando webhooks [Vídeo da aula](https://www.youtube.com/watch?v=Xggsb_cRa_w) ## Resposta rápida Vá em **Automação → Webhooks → Criar**, dê um nome e abra o webhook para copiar a **URL**. Cole essa URL na outra ferramenta (formulário, CRM, etc.) para que ela avise o BotConversa quando algo acontecer. Mapeie o conteúdo recebido (telefone, nome) para criar ou atualizar contatos. Teste no **Modo Teste** e só depois ative. **Tempo de leitura:** ~6 min**Para quem é:** Gestor | Marketing | Dono do negócio ## 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). ![Tela de Automação com a aba Webhooks e o indicador de limite de requisições](https://lfdfrrdzcfagillurinx.supabase.co/storage/v1/object/public/article-images/03-automacoes/configurando-webhooks/passo-1.png) Tela de Automação com a aba Webhooks e o indicador de limite de requisições ### 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**. ![Janela de criação do webhook com o campo Nome preenchido](https://lfdfrrdzcfagillurinx.supabase.co/storage/v1/object/public/article-images/03-automacoes/configurando-webhooks/passo-2.png) Janela de criação do webhook com o campo Nome preenchido ### 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. ![Editor do webhook com a URL e o botão de copiar em destaque](https://lfdfrrdzcfagillurinx.supabase.co/storage/v1/object/public/article-images/03-automacoes/configurando-webhooks/passo-3.png) Editor do webhook com a URL e o botão de copiar em destaque ### 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. ![Painéis Requisições e Ações com os campos telefone e nome mapeados](https://lfdfrrdzcfagillurinx.supabase.co/storage/v1/object/public/article-images/03-automacoes/configurando-webhooks/passo-6.png) Painéis Requisições e Ações com os campos telefone e nome mapeados ### 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. ## Dicas - Sempre teste com um envio de exemplo antes de ativar. - Confira que o número de telefone chega com o DDI (o código do país, como o 55 do Brasil). - Dê nomes claros aos webhooks por origem (ex.: "Leads Landing Page", "Pedidos Loja"). - Fique de olho no **limite de requisições** da sua conta, que soma as chamadas de todos os webhooks. ## Casos de uso **Negócio com landing page:** o formulário do site envia cada novo lead para o webhook. O contato é criado no BotConversa na hora e já pode entrar num fluxo de boas-vindas. **E-commerce:** a cada pedido confirmado, a plataforma de vendas avisa o webhook. O contato é atualizado e o BotConversa pode disparar a mensagem de "pedido recebido". **🎯 Missão desta aula:** crie um webhook, copie a URL e dispare um teste a partir de um formulário ou de uma ferramenta externa. **Checkpoint:** o contato de teste foi criado ou atualizado no BotConversa a partir da chamada. ## Perguntas frequentes Para que serve o Modo Teste? Para configurar com segurança. Nele o webhook captura um exemplo de dados, mas não dispara ações reais. Você só ativa depois de conferir o mapeamento. Por que meu webhook não está disparando? Confira se ele saiu do Modo Teste (está ativo), se a URL foi colada corretamente na outra ferramenta e se o mapeamento de telefone e nome está certo. Veja [Webhook não está disparando](/aula/webhook-nao-esta-disparando). Tem limite de chamadas? Sim. Existe um teto de requisições por conta, exibido no topo da aba Webhooks. Ele soma as chamadas de todos os seus webhooks. Webhook é a mesma coisa que o Integrador? Não. O webhook de entrada é uma forma simples de receber dados. O Integrador é uma camada mais ampla para conectar vários aplicativos. Veja [Conectando com outras ferramentas (Integrador)](/aula/conectando-com-outras-ferramentas-integrador).