Webhook é o mecanismo que permite que um sistema avise outro, automaticamente e no instante em que algo acontece. Em vez de o seu sistema ficar perguntando de minuto em minuto "já entrou algum pagamento?", ele informa um endereço na internet e o sistema de pagamento envia um aviso para esse endereço no momento exato em que o PIX cai. Tecnicamente, um webhook é uma requisição HTTP que o sistema de origem dispara para uma URL do destino, carregando os dados do evento — normalmente em formato JSON. É por isso que também é chamado de callback HTTP ou API reversa: em vez de você chamar a API, a API chama você. É esse mecanismo que faz a mensagem do WhatsApp chegar ao seu agente de IA, o pagamento aprovado disparar a mensagem de confirmação e a mudança de etapa no CRM acionar o follow-up.

Qual a diferença entre webhook e API?

São complementares e a confusão é comum. A diferença está em quem toma a iniciativa:

  • API (você pergunta): seu sistema faz uma chamada e recebe uma resposta. "Me diga o status do pedido 4837." Você controla quando perguntar.
  • Webhook (o outro avisa): o sistema de origem envia os dados quando o evento acontece. "O pedido 4837 acabou de ser pago." Você controla apenas onde receber.

A alternativa ao webhook é o polling: perguntar repetidamente. Funciona, mas é caro e lento. Consultar a cada 5 minutos significa, na prática, até 5 minutos de atraso e centenas de chamadas inúteis por dia — em 99% delas a resposta é "nada mudou". Além disso, muitos serviços cobram por chamada ou limitam o volume, então polling agressivo custa dinheiro e derruba a integração.

Regra prática: quando você precisa reagir rápido a algo que acontece do outro lado, webhook. Quando você precisa buscar informação sob demanda ou trazer histórico em massa, API.

Como funciona um webhook, passo a passo

  1. Você cria um endereço para receber. É uma URL do seu sistema, pública e com HTTPS, feita só para escutar aquele tipo de evento.
  2. Você registra essa URL no painel do sistema de origem e escolhe quais eventos quer receber — pagamento aprovado, mensagem recebida, negócio movido, nota autorizada.
  3. O evento acontece no sistema de origem.
  4. O sistema envia uma requisição para a sua URL, com os dados do evento no corpo da mensagem.
  5. Seu sistema responde rapidamente confirmando o recebimento. Essa confirmação diz apenas "recebi", não "processei".
  6. O processamento acontece em segundo plano, de preferência a partir de uma fila.
  7. Se você não confirmar o recebimento, a maioria dos serviços tenta de novo, várias vezes, com intervalos crescentes. Isso é bom para não perder evento — e é a razão de você precisar tratar recebimentos repetidos.

Onde você já usa webhook sem saber

  • WhatsApp: toda mensagem que um cliente envia para um número na API oficial chega ao seu sistema por webhook. É isso que permite ao agente de IA responder em cerca de 3 segundos. Sem webhook, não existiria atendimento automatizado em tempo real.
  • PIX e cartão: o banco ou o gateway avisa quando o pagamento é confirmado. É o que permite liberar o pedido, enviar a confirmação e baixar o título automaticamente, sem alguém conferindo extrato.
  • NF-e: a autorização da nota pela SEFAZ pode ser comunicada ao seu sistema, que então envia o documento ao cliente e atualiza o pedido.
  • Formulários e anúncios: um cadastro preenchido dispara o aviso e o lead entra no funil na hora, em vez de esperar alguém baixar planilha.
  • CRM e ERP: mudança de etapa, criação de pedido ou alteração de cadastro notificam os demais sistemas.
  • Ferramentas de automação: quase toda plataforma de automação usa webhook como gatilho de partida.

Um exemplo de ponta a ponta

Uma loja recebe um pedido por WhatsApp e a operação inteira acontece sem intervenção humana:

  1. O cliente manda mensagem. O WhatsApp dispara um webhook para o sistema, que entrega a conversa ao agente de IA.
  2. O agente entende o pedido, consulta estoque via API do ERP e confirma disponibilidade.
  3. O sistema gera uma cobrança PIX chamando a API do provedor de pagamento e devolve o código ao cliente.
  4. O cliente paga. O provedor dispara um webhook de pagamento confirmado.
  5. Ao receber esse aviso, o sistema registra a baixa, cria o pedido no ERP e pede a emissão da nota.
  6. A autorização da nota chega por webhook e dispara o envio do documento e do código de rastreio pelo WhatsApp.
  7. Cada etapa é registrada no CRM.

Repare que os webhooks são as engrenagens que fazem a corrente girar sozinha. Sem eles, cada passo dependeria de alguém conferindo alguma tela.

O que é preciso para receber webhooks com segurança

  • Endereço público com HTTPS. O sistema de origem precisa alcançar seu servidor pela internet, com tráfego criptografado.
  • Disponibilidade. Se seu sistema fica fora do ar, eventos se acumulam e podem ser descartados depois de um número limitado de tentativas. Monitore.
  • Validação de autenticidade. Sua URL é pública, então qualquer um pode tentar enviar dados falsos para ela. Serviços sérios assinam a requisição com um segredo compartilhado; seu sistema deve conferir essa assinatura e recusar o que não bate. Alguns exigem também uma etapa inicial de verificação para confirmar que a URL é sua.
  • Resposta rápida. Confirme o recebimento em poucos segundos. Processar tudo antes de responder gera tempo esgotado, o que faz o remetente reenviar e multiplica o trabalho.
  • Fila de processamento. Receba, guarde, responda e processe depois. É o padrão que sustenta volume e permite reprocessar em caso de falha.
  • Registro de tudo que chega. Sem log, investigar "por que aquele pagamento não apareceu" é impossível.

Erros comuns e como evitá-los

  • Não tratar duplicidade. O mesmo evento pode chegar mais de uma vez — por retentativa ou por falha de rede. Se o seu sistema criar dois pedidos, você tem um problema real. A solução é usar o identificador do evento como chave única e ignorar o que já foi processado. Isso se chama idempotência e é a regra número um de integração.
  • Assumir ordem de chegada. Eventos podem chegar fora de sequência: o "pedido enviado" antes do "pedido pago". Confie na data do evento e na regra de negócio, nunca na ordem de recebimento.
  • Processar de forma síncrona. Emitir nota, enviar e-mail e atualizar três sistemas antes de responder é receita para tempo esgotado e reenvio em cascata.
  • Ignorar a assinatura. Endpoint aberto sem validação aceita qualquer coisa que alguém enviar. Já vi sistema dando baixa em pagamento que nunca existiu por causa disso.
  • Quebrar com campo novo. Provedores adicionam campos com o tempo. Seu sistema deve ignorar o que não conhece, em vez de falhar.
  • Não avisar quando falha. Integração que para em silêncio é pior que integração inexistente, porque todo mundo continua confiando nela. Alerta de falha é obrigatório.
  • Esquecer o ambiente de teste. Testar em produção com pagamento real é caro. Use ambiente de homologação e ferramentas que permitam reenviar eventos.

Quando webhook não é a resposta

  • Quando o sistema de origem não oferece. Muitos sistemas legados e algumas ferramentas nacionais não têm webhook. Nesse caso, polling programado é a alternativa legítima.
  • Quando você precisa de histórico. Webhook conta o que acontece de agora em diante. Para carregar dois anos de pedidos, é API ou exportação.
  • Quando o dado precisa estar rigorosamente consistente em todo instante entre dois sistemas. Nesse caso, além de eventos, é preciso uma rotina periódica de reconciliação — comparar os dois lados e corrigir divergências. Nenhuma integração séria dispensa esse ajuste de contas.
  • Quando o volume é baixo e o processo é manual mesmo. Duas notas por dia não justificam infraestrutura de eventos.

Na prática, quase toda automação bem construída de PME combina os três: webhooks para reagir na hora, chamadas de API para buscar e gravar dados, e uma rotina de conferência periódica para garantir que nada ficou pelo caminho. Na IA365, essa arquitetura de eventos é a base de praticamente todos os projetos de integração, porque é ela que permite responder em segundos em vez de minutos.

Perguntas frequentes

Preciso saber programar para usar webhooks?

Para desenhar a solução, não — mas alguém precisa construir e manter a camada que recebe os eventos. Plataformas de automação permitem criar receptores de webhook sem escrever código, o que resolve casos simples. Fluxos críticos, com dinheiro ou documento fiscal envolvido, pedem tratamento adequado de idempotência, fila e monitoramento, e aí é trabalho de desenvolvimento.

Webhook é seguro? Qualquer um pode mandar dados para o meu endereço?

Tecnicamente, qualquer um pode tentar. Por isso a segurança não está em esconder a URL, e sim em validar quem enviou: verificação de assinatura com segredo compartilhado, uso de HTTPS, e checagem de que o conteúdo faz sentido antes de agir. Tratado dessa forma, é um mecanismo seguro e usado por praticamente todos os grandes serviços.

O que acontece se meu sistema estiver fora do ar quando o evento ocorrer?

A maioria dos provedores tenta reenviar por um período, com intervalos crescentes. Se o seu sistema voltar dentro dessa janela, os eventos chegam com atraso e nada se perde. Se a indisponibilidade for longa, eventos podem ser descartados — e é aí que a rotina de reconciliação salva a operação.

Qual a diferença entre webhook e integração em tempo real?

Webhook é uma das formas de fazer integração em tempo real, e a mais comum na web. Existem outras, como conexões persistentes usadas em aplicações de mensagem instantânea e filas de mensagens em arquiteturas maiores. Para o cenário típico de uma PME conectando WhatsApp, CRM, ERP e pagamentos, webhook é o padrão adequado.