Webhook é uma forma de um sistema avisar outro automaticamente quando um evento acontece. Em vez de uma aplicação ficar perguntando de tempos em tempos se há novidades, o serviço de origem envia uma requisição HTTP para um endereço definido por você. Esse modelo é usado em pagamentos, CRMs, mensageria, automações, GitHub, formulários e integrações com n8n.
Na prática, um webhook transforma um acontecimento em um gatilho: um pagamento aprovado pode iniciar a emissão de uma nota; um novo lead pode entrar no CRM; uma mensagem recebida pode acionar um chatbot; e um novo commit pode começar uma rotina de deploy. A ideia parece simples, mas uma integração confiável precisa tratar segurança, respostas rápidas, duplicidade, falhas e mudanças no formato dos dados.
O que é um webhook
Um webhook é um endpoint HTTP preparado para receber dados enviados por outro sistema. Normalmente, o serviço remetente faz uma requisição POST com um corpo em JSON, embora também possa usar outros métodos e formatos conforme a documentação da integração. O endereço de recebimento costuma ser chamado de URL do webhook.
A diferença principal para uma consulta tradicional, ou polling, está em quem inicia a comunicação. No polling, o sistema consumidor pergunta repetidamente: “há um novo pedido?”. No webhook, o sistema produtor envia uma notificação quando o pedido muda de estado. Isso pode reduzir chamadas desnecessárias e diminuir o intervalo entre o evento e a reação.
Webhook não é uma API completa nem um protocolo separado do HTTP. Ele é um padrão de integração baseado em uma chamada HTTP para um endpoint público ou acessível ao serviço que fará o envio. Por isso, os detalhes variam: cada fornecedor define eventos, campos, cabeçalhos, assinatura, política de reenvio e códigos de resposta aceitos.
Como funciona um webhook passo a passo
- Um evento ocorre: por exemplo, um cliente preenche um formulário, um pagamento é confirmado ou um registro é atualizado.
- O sistema de origem monta o payload: ele reúne o tipo do evento, um identificador e os dados necessários para o destino.
- O serviço envia uma requisição HTTP: geralmente para uma URL HTTPS cadastrada previamente.
- O endpoint recebe e valida a chamada: o servidor verifica assinatura, origem, formato e se o evento é realmente relevante.
- A aplicação responde: uma resposta 2xx indica recebimento aceito. O processamento pesado pode continuar em fila ou em segundo plano.
- O consumidor executa a ação: grava dados, chama outra API, envia uma mensagem ou inicia um fluxo de automação.
O payload deve conter informação suficiente para identificar o evento, mas não precisa carregar todos os dados do sistema de origem. Em muitos casos, o caminho mais seguro é receber o ID do objeto e consultar a API oficial depois de validar a assinatura. Essa estratégia também reduz o risco de confiar em dados antigos ou incompletos.
Webhook, API e polling: qual é a diferença?
| Modelo | Quem inicia | Quando usar | Limitação |
|---|---|---|---|
| Webhook | Sistema de origem | Reagir a eventos quase em tempo real | Exige endpoint acessível e tratamento de falhas |
| API sob demanda | Sistema consumidor | Buscar ou alterar um recurso quando necessário | A aplicação precisa saber quando consultar |
| Polling | Sistema consumidor, repetidamente | Quando o fornecedor não oferece webhook | Pode gerar chamadas e atrasos desnecessários |
Os modelos podem coexistir. Um webhook pode avisar que um pedido mudou, enquanto a aplicação consulta a API para obter os detalhes atuais. Também é comum usar polling como alternativa quando a entrega de eventos não é confiável ou quando o serviço não oferece notificações.
Exemplos de uso em empresas
Pagamentos e pedidos
Um gateway pode enviar eventos de pagamento aprovado, recusado ou estornado. O sistema da loja recebe a notificação, confere sua autenticidade e atualiza o pedido. A confirmação não deve depender somente da página de retorno exibida ao comprador, porque o cliente pode fechar o navegador antes que ela seja carregada.
CRM e atendimento
Um formulário de contato pode enviar novos leads para um CRM. A automação pode normalizar telefone e e-mail, verificar duplicidade, atribuir o responsável e disparar uma mensagem. Em mensageria, o mesmo princípio permite receber eventos de entrega, resposta ou mudança de status e encaminhá-los para um fluxo de atendimento.
Desenvolvimento de software
Serviços como repositórios de código podem notificar uma aplicação quando há push, abertura de pull request ou alteração de issue. A aplicação então roda testes, atualiza um painel ou inicia uma etapa de entrega contínua. O evento deve ser filtrado por tipo e ação, em vez de tratar todo payload como se fosse igual.
Automação com n8n
No n8n, o Webhook node oferece uma URL de teste e outra de produção. A documentação do n8n orienta usar a URL de teste enquanto o fluxo está sendo construído e publicado, e trocar para a URL de produção quando o workflow estiver pronto. A URL de teste fica disponível por um período limitado após o modo de escuta ser ativado; a URL de produção depende do workflow publicado.
Isso é útil para conectar formulários, sistemas internos e APIs sem escrever todo o servidor do zero. Ainda assim, o n8n não elimina a necessidade de validar a entrada, proteger o endpoint e pensar no tempo de resposta. Para cenários de automação residencial ou dispositivos conectados, veja também o que é computação de borda e como ela funciona, pois o processamento local pode complementar integrações dependentes da nuvem.
Segurança: como proteger um webhook
Não trate o fato de uma requisição ter chegado à URL como prova de autenticidade. Um endpoint público pode receber chamadas de qualquer origem. A proteção mais comum é uma assinatura HMAC: o remetente calcula um resumo criptográfico usando o corpo original e um segredo compartilhado; o receptor refaz o cálculo e compara os valores com uma comparação segura.
A documentação do GitHub recomenda validar a assinatura antes de processar o payload, guardar o segredo fora do código e usar o cabeçalho X-Hub-Signature-256, baseado em HMAC-SHA-256. O corpo precisa ser preservado no formato original durante a validação. Se um proxy alterar o conteúdo antes da conferência, uma assinatura correta poderá parecer inválida.
Use HTTPS com certificado válido e não coloque chaves de API ou senhas na própria URL. Quando o fornecedor disponibilizar uma lista de IPs, ela pode ser usada como camada adicional, mas não substitui a assinatura. Também vale limitar os eventos assinados ao mínimo necessário e rejeitar métodos, tipos de conteúdo ou tamanhos inesperados.
Evite o processamento duplicado
Um serviço pode reenviar um evento quando não recebe uma resposta esperada. Portanto, o consumidor deve ser idempotente: salvar o identificador da entrega ou do evento e evitar repetir efeitos irreversíveis. Em vez de criar duas cobranças ou dois tickets, a segunda tentativa deve ser reconhecida como já processada.
Também é importante separar recebimento de processamento. A aplicação pode validar, registrar o evento e colocá-lo em uma fila antes de responder. O GitHub recomenda retornar uma resposta 2xx em até 10 segundos; trabalhos demorados devem ocorrer de forma assíncrona. O limite exato muda por fornecedor, então confira sempre a documentação da integração.
Limitações e problemas comuns
Webhooks dependem de conectividade, disponibilidade e regras do serviço remetente. Se o endpoint estiver fora do ar, se o certificado estiver inválido ou se a resposta demorar, a entrega pode falhar. Alguns fornecedores fazem novas tentativas automaticamente; outros exigem reenvio manual ou não garantem a mesma política. Não presuma que todo webhook é uma fila durável.
Entre os erros mais frequentes estão usar a URL de teste em produção, aceitar eventos sem conferir assinatura, assumir que a ordem de entrega é sempre perfeita, não registrar o payload para diagnóstico e esquecer de atualizar o endpoint quando o domínio muda. Em ferramentas de automação, conflitos entre o mesmo caminho e método HTTP também podem impedir o registro de mais de um webhook.
Um diagnóstico organizado começa verificando se a chamada chegou, qual foi o código de resposta, quais cabeçalhos foram recebidos e se a assinatura corresponde ao corpo original. Depois, confira o tipo do evento, a estrutura do JSON e os logs da ação seguinte. Um endpoint que responde sucesso antes de salvar o evento pode perder dados se o processo cair imediatamente depois.
Como desenhar uma integração confiável
- Defina quais eventos realmente precisam gerar ação.
- Crie uma URL HTTPS dedicada e documente o método e o formato aceitos.
- Configure um segredo aleatório e valide a assinatura antes de interpretar os dados.
- Registre o ID da entrega, horário, resultado da validação e status do processamento.
- Responda rapidamente e mova tarefas demoradas para uma fila.
- Implemente idempotência e uma estratégia de reprocessamento.
- Monitore erros, atrasos, volume e mudanças no contrato do payload.
- Teste eventos reais e casos de falha antes de ativar o fluxo.
Esse desenho permite começar pequeno, mas sem confundir simplicidade com ausência de controle. Um webhook é um ótimo gatilho, não uma garantia automática de entrega perfeita. Para decisões financeiras, atendimento ao cliente ou atualização de estoque, combine a notificação com consulta de confirmação, logs e uma rotina de reconciliação.
Perguntas frequentes
Webhook precisa de um servidor próprio?
Não necessariamente. Você pode usar um endpoint de uma plataforma de automação, como n8n, ou um serviço especializado. Porém, ainda precisa controlar autenticação, permissões, logs, limites e o destino dos dados.
Webhook funciona sem internet?
Em geral, a entrega entre serviços depende de uma rede acessível. Um sistema local pode receber eventos dentro da própria rede, mas um fornecedor externo normalmente precisará alcançar o endpoint pela internet ou por uma conexão privada.
Qual código HTTP devo retornar?
Use o código indicado pelo fornecedor. Em muitos casos, uma resposta da família 2xx confirma o recebimento. Ela não significa necessariamente que todo o processamento de negócio terminou; isso deve ser acompanhado por logs e pelo estado da fila.
É seguro colocar o webhook em uma URL pública?
Pode ser seguro quando o endpoint usa HTTPS, valida assinatura, limita entradas, evita credenciais na URL e monitora tentativas inválidas. Uma URL pública sem autenticação adequada deve ser considerada exposta.