O que é webhook: o aviso entre sistemas e quando ele se perde no caminho

Quase todo guia sobre webhook termina na mesma frase: ele entrega os dados em tempo real. É verdade quando tudo está no ar. A pergunta que decide se a integração entre site, CRM e automação é confiável é outra: o que acontece com o aviso quando o sistema que deveria recebê-lo está fora do ar, lento ou respondendo com erro.

Este guia explica o que é webhook e como ele funciona, sem pressupor que você programa. Depois mostra, com a documentação oficial de três CRMs muito usados no Brasil, quantas vezes cada um tenta entregar o aviso antes de desistir, e o que a integração precisa ter para que uma queda de servidor não vire lead perdido sem que ninguém perceba.

O que é webhook e como funciona?

Webhook é uma forma de um sistema avisar outro, automaticamente, que um evento aconteceu. Em vez de o sistema interessado perguntar o tempo todo se há novidade, ele deixa cadastrado um endereço, e o sistema de origem manda uma mensagem para esse endereço sempre que o evento ocorre: um formulário preenchido, um lead que virou oportunidade, um negócio que mudou de etapa, uma mensagem recebida no WhatsApp.

Tecnicamente, o aviso é uma requisição HTTP, normalmente do tipo POST, com os dados do evento no corpo, em geral no formato JSON. Quem recebe processa a mensagem e devolve uma resposta. Essa resposta é o que fecha o ciclo: um código da família 2xx diz ao remetente que o aviso chegou; qualquer outra coisa, ou o silêncio, diz que falhou.

Por isso muita gente descreve o webhook como uma API ao contrário. Na API comum, quem quer o dado vai buscá-lo. No webhook, o dado vem até você. A analogia ajuda, mas esconde o detalhe que mais importa para quem depende do aviso: quem decide quantas vezes ele é reenviado em caso de falha é o remetente, e cada plataforma tem a sua regra.

Para que serve um webhook na integração de sistemas?

Serve para que um sistema reaja a outro sem atraso e sem gastar recursos perguntando à toa. Em marketing e vendas, os usos mais comuns são previsíveis, e quase todos envolvem o lead:

• Lead convertido na ferramenta de automação vira contato e negócio no CRM, ou dispara uma mensagem para o vendedor.
• Negócio ganho no CRM avisa o ERP para emitir pedido e nota, e a ferramenta de e-mail para tirar o contato da nutrição de prospects.
• Mensagem recebida no WhatsApp chega ao sistema de atendimento ou ao chatbot que vai respondê-la.
• Pagamento confirmado libera o acesso, atualiza o status do pedido e alimenta o painel de vendas.
• Evento em plataforma de automação, como n8n, Make ou Zapier, inicia um fluxo que distribui o dado para vários sistemas ao mesmo tempo.

Em todos esses casos, o webhook é a ponta de um processo comercial. Se o aviso não chega, não é um erro técnico abstrato: é o vendedor que não liga, o cliente que pagou e não recebeu acesso, o pedido que não foi faturado. É o mesmo tipo de prejuízo que tratamos ao falar sobre o custo do dado partido entre sistemas, só que com uma causa mais difícil de enxergar.

Qual a diferença entre webhook e API?

Webhook e API não são a mesma coisa, mas também não são rivais. A API é a interface que um sistema oferece para ser consultado e alterado: ler um contato, criar um negócio, atualizar um status. O webhook é o recurso que avisa que algo mudou. Na prática, uma integração madura usa os dois: o webhook avisa, e a API completa, corrige e confere.

Comparativo elaborado pela Alliance Comunicação a partir de projetos de integração de CRM.

A linha que mais pesa na tabela é a quarta. A consulta periódica é lenta e gasta cota, mas é tolerante: se o sistema que consulta cair por uma hora, na volta ele pergunta de novo e recebe tudo. O webhook é rápido e econômico, mas depende de o receptor estar disponível na janela em que o remetente insiste. A economia de cota foi tema do nosso guia sobre o limite de API que o plano do CRM impõe; aqui o assunto é o outro lado da troca.

O que é a URL do webhook?

A URL do webhook é o endereço que recebe o aviso. Você a cadastra no sistema de origem (no painel do CRM, na ferramenta de automação ou pela API dele) e escolhe quais eventos devem ser enviados para lá. Ela pertence a quem recebe: pode ser um servidor da própria empresa, uma plataforma de automação como o n8n ou um serviço do fornecedor da integração.

Três cuidados com essa URL evitam boa parte dos problemas. Ela precisa ser pública e usar HTTPS, já que o remetente está na internet. Ela precisa ter dono, porque é comum ninguém lembrar quem cadastrou um endereço antigo que continua recebendo dados de clientes. E ela precisa responder depressa, porque, como mostram as regras abaixo, o remetente não espera muito.

O que acontece se o webhook falhar?

Quando o receptor não responde, demora demais ou devolve erro, o remetente considera a entrega falha e agenda uma nova tentativa. Esse é o comportamento esperado. O que muda de uma plataforma para outra é o prazo de resposta, o número de reenvios e o intervalo entre eles, e essas três coisas estão escritas na documentação de cada fornecedor.

Há dois detalhes nas mesmas páginas que mudam a leitura. No HubSpot, os webhooks disparados por workflows seguem regra própria: não tentam de novo depois de receber uma resposta 4xx, com exceção do erro 429 (limite de requisições), em que o workflow repete e respeita o cabeçalho Retry-After. No Pipedrive, a página afirma que, enquanto o webhook está banido, a mensagem do evento é perdida, e que um webhook sem nenhuma entrega bem-sucedida por 3 dias seguidos é apagado.

Quantas vezes HubSpot, RD Station e Pipedrive tentam de novo?

Lado a lado, as três regras mostram que a palavra webhook descreve mecanismos com tolerâncias muito diferentes. O mesmo receptor, com a mesma instabilidade, perde dados num CRM e não perde em outro.

Documentação oficial de HubSpot (Error handling), RD Station (Retries Logic) e Pipedrive (Guide for Webhooks v2), consultadas em outubro de 2026.

Duas ressalvas para ler a tabela com honestidade. Primeiro, o RD Station não publica o intervalo entre os 3 reenvios, então não dá para afirmar se eles cobrem segundos, minutos ou horas; quem depende dele deve tratar a janela como curta até ter evidência do contrário. Segundo, essas regras mudam: confira a página oficial no dia em que desenhar a integração.

O que uma queda de 10 minutos faz com os leads?

Imagine o servidor que recebe os avisos fora do ar por 10 minutos, numa atualização mal feita ou num certificado vencido, numa manhã de campanha. Cada lead que entrar nesse intervalo gera um aviso que falha na primeira tentativa. O que acontece em seguida depende do remetente.

No Pipedrive, as três novas tentativas acontecem em até 183 segundos (3 + 30 + 150) depois da falha original. Todas caem dentro da queda. O aviso conta como entrega malsucedida, e não há mais tentativa prevista na documentação. Se a queda gerar 10 falhas na primeira tentativa, o webhook ainda é banido por 30 minutos, e os eventos desse período também se perdem, mesmo que o servidor já tenha voltado.

No HubSpot, o mesmo aviso ainda tem o resto do dia: até 10 reenvios distribuídos em 24 horas. Uma queda de 10 minutos tende a ser absorvida. Uma queda de um fim de semana, não. No RD Station, como a documentação não diz o intervalo entre os 3 reenvios, a única afirmação segura é que, esgotados os três, a notificação não volta.

Webhook não garante entrega. Ele garante algumas tentativas, num prazo que quem escreve é o remetente.

O problema não é a falha em si, é o silêncio. Nenhuma das três plataformas manda o lead perdido por e-mail para alguém. Do ponto de vista do vendedor, o lead simplesmente não existiu. Por isso a pergunta certa para quem contrata uma integração não é se ela usa webhook, e sim o que acontece quando o webhook esgota as tentativas.

Por que o mesmo lead às vezes chega duas vezes?

Porque o reenvio é cego. O remetente não sabe se o receptor processou o aviso e só demorou para responder, ou se nem chegou a recebê-lo. Na dúvida, ele manda de novo. Se o receptor gravou o lead na primeira vez e respondeu depois do prazo, a segunda tentativa cria um duplicado.

O próprio RD Station diz isso na página de reenvios: notificações chegando em duplicidade indicam que o endpoint está levando mais de 5 segundos para responder. Ou seja, a duplicata é um sintoma de lentidão, não um capricho da plataforma. E ela custa caro: contato repetido no CRM, duas tarefas para o vendedor, dois e-mails de boas-vindas, relatório de conversão inflado.

A solução tem nome técnico, idempotência, e uma ideia simples: processar o mesmo aviso duas vezes precisa produzir o mesmo resultado que processá-lo uma vez. O jeito mais comum é guardar o identificador de cada evento já tratado e ignorar o que se repete. No Pipedrive, por exemplo, a mensagem do webhook traz um campo id do evento e um campo attempt com o número da tentativa, que ajudam a montar essa checagem.

Como montar um receptor de webhook que não perde lead?

Não é preciso infraestrutura sofisticada. É preciso separar o que é urgente (confirmar o recebimento) do que é demorado (gravar no CRM, consultar outro sistema, enviar mensagem). Os passos abaixo valem para servidor próprio, função na nuvem ou plataforma de automação.

1. Responda 2xx antes de processar

O receptor deve guardar o aviso e responder imediatamente, deixando o trabalho pesado para depois. Quem grava no CRM, consulta o ERP e só então responde está apostando que tudo isso cabe em 5 segundos, sempre, inclusive no pico. Quando não cabe, o remetente considera falha e reenvia, e começa a duplicata.

2. Coloque o aviso numa fila

A fila é o lugar onde o evento espera até ser processado. Se o CRM de destino estiver lento ou fora do ar, o evento continua guardado, e o processamento tenta de novo com espera crescente. A fila transfere a responsabilidade pela nova tentativa do remetente, que tem regra fixa, para você, que pode decidir quanto insistir.

3. Trate a duplicata pelo identificador do evento

Antes de gravar, confira se aquele evento já foi tratado. Se a plataforma manda um identificador, use-o; se não manda, combine campos que identifiquem o evento sem ambiguidade. No CRM, procure o contato pelo e-mail ou pelo identificador externo antes de criar um novo.

4. Monitore as falhas e avise alguém

Registre cada aviso recebido e cada erro de processamento, e crie um alerta quando o volume cair abaixo do normal. Um dia de campanha sem nenhum webhook recebido não é calmaria, é sinal de que algo quebrou do outro lado.

5. Concilie pela API o que o webhook perdeu

Este é o passo que tira a integração da sorte. Em intervalos regulares, uma rotina consulta pela API os registros criados ou alterados no período e compara com o que chegou ao destino. O que faltar é reprocessado. A conciliação é exatamente a consulta periódica que o webhook veio substituir, só que rodando poucas vezes por dia, como rede de segurança, e não a cada minuto.

Como testar um webhook antes de confiar nele?

O teste comum confere se o aviso chega. O teste que importa confere o que acontece quando ele não chega. Vale fazer os dois, nesta ordem:

1. Teste de chegada: dispare um evento real (uma conversão de teste, um negócio de teste) e confira se o receptor recebeu os campos esperados, no formato esperado.
2. Teste de lentidão: faça o receptor demorar mais que o prazo do remetente e veja se surgem duplicatas no destino. Se surgirem, a checagem de identificador não está funcionando.
3. Teste de queda: desligue o receptor por alguns minutos, gere eventos e religue. Conte quantos chegaram e quantos só a conciliação recuperou.
4. Teste de erro no destino: simule o CRM de destino fora do ar e confira se os eventos ficam na fila e são processados depois.
5. Teste de volume: gere uma rajada de eventos, como num dia de campanha, e acompanhe o tempo de resposta do receptor.

Em plataformas de automação, há um cuidado extra com o ambiente de teste. No n8n, por exemplo, a documentação do nó Webhook explica que existe uma URL de teste, registrada quando você manda o editor escutar um evento, e uma URL de produção, registrada quando o fluxo é publicado. Integração testada na URL de teste e cadastrada no CRM com esse mesmo endereço para de receber quando o editor é fechado.

Webhook no WhatsApp, no n8n e no RD Station: o que muda?

O conceito é o mesmo em todos; mudam os eventos e a tolerância a falha. Três casos que aparecem com frequência em projetos de marketing e vendas:

• RD Station: segundo a documentação do serviço de webhooks, os eventos do RD Station Marketing incluem conversão (todo lead que converte, ou só as conversões escolhidas) e oportunidade (lead marcado como oportunidade, à mão, por integração ou por fluxo de automação); há também eventos de negociação do RD Station CRM. A regra de reenvio é a da tabela acima: 3 tentativas e depois falha definitiva.
• WhatsApp: na API oficial da Meta (Cloud API), o webhook entrega as mensagens recebidas e o status das mensagens enviadas. A documentação de configuração de webhooks da Cloud API informa que, se o endpoint não responder com sucesso, a Meta repete a entrega com frequência decrescente por até 7 dias, e que isso pode gerar notificações duplicadas.
• n8n e plataformas de automação: elas costumam ser o receptor. Ganham facilidade, mas herdam a responsabilidade: se o fluxo grava direto no CRM e demora, a duplicata aparece; se a plataforma cai, valem as regras de reenvio de quem envia.

Repare na diferença de escala: a Meta insiste por dias, o Pipedrive por minutos. Quem integra WhatsApp e CRM no mesmo fluxo precisa desenhar o receptor para o remetente menos tolerante. Se o assunto é a operação de atendimento pelo WhatsApp, o guia sobre o que se paga na API do WhatsApp Business complementa este.

Quais os erros mais comuns com webhook?

• Processar tudo antes de responder. O receptor estoura o prazo de 5 ou 10 segundos no pico e transforma cada lead em dois.
• Tratar o webhook como entrega garantida. Sem conciliação, o que esgota as tentativas some sem registro.
• Não saber qual é a regra do remetente. Integrações que juntam vários sistemas herdam a menor janela de reenvio entre eles.
• Cadastrar a URL de teste em produção. Funciona enquanto alguém está com o editor aberto.
• URL sem dono. Endereço antigo continua recebendo dados de clientes, ou o certificado vence e ninguém percebe.
• Ignorar o banimento. No Pipedrive, falhas repetidas na primeira tentativa suspendem o webhook por 30 minutos, e os eventos desse intervalo se perdem.
• Medir só o erro, não a ausência. Falha que não gera aviso só aparece quando alguém compara os números dos dois lados.

Por onde começar hoje

Faça uma lista de todos os webhooks cadastrados nos sistemas da empresa: de onde saem, para qual URL vão, quem responde por cada um. Para cada remetente, anote o prazo de resposta e a regra de reenvio que a documentação oficial informa. Depois rode o teste de dois minutos acima e compare os números de ontem. Se houver diferença, o próximo passo é a conciliação via API, antes de qualquer outra melhoria.

Se a dúvida é onde o funil perde informação entre marketing, vendas e atendimento, o diagnóstico gratuito de marketing avalia dados, tecnologia e relacionamento junto com as demais dimensões. E quando o passo for desenhar a integração do CRM com site, automação, ERP e WhatsApp, com fila, tratamento de duplicata e conciliação, esse é o trabalho de integração de CRM e dados da Alliance: do diagnóstico à ação.