Evento explícito
Cada mensagem precisa indicar o que ocorreu e carregar um identificador único. O consumidor consegue decidir qual processamento executar e evitar repetições indevidas.
Eventos e automações entre sistemas
O que é webhook? Entenda como sistemas notificam eventos em tempo real
Webhook é uma notificação enviada automaticamente por um sistema quando um evento relevante ocorre. Em vez de consultar repetidamente uma API para descobrir se um pagamento foi aprovado ou se um lead chegou, a aplicação recebe uma chamada no endereço configurado.
Ao final deste guia, você saberá
- Diferenciar webhook de consulta periódica e chamada comum de API.
- Entender evento, endpoint receptor, payload e confirmação de recebimento.
- Tratar assinatura, duplicidade, ordem e reprocessamento corretamente.
- Usar webhooks em pagamentos, CRM, ERP, WhatsApp e automações n8n.
Definição aplicada
Webhook é um mecanismo de entrega orientado a eventos
Quando um sistema publica um webhook, ele oferece uma forma de avisar consumidores sobre mudanças relevantes. O consumidor cadastra um endpoint receptor; quando determinado evento ocorre, o publicador envia uma requisição com um payload. O receptor valida a mensagem, registra o evento, confirma o recebimento rapidamente e executa o processamento necessário.
Essa arquitetura reduz consultas repetitivas, conhecidas como polling. Sem webhook, uma aplicação interessada em confirmações de pagamento poderia consultar a API a cada minuto mesmo quando nada mudou. Com eventos, o sistema reage quando existe informação nova. Ainda assim, a API continua importante: ela pode ser usada para buscar detalhes, confirmar estado ou reconciliar dados posteriormente.
A simplicidade aparente esconde decisões operacionais. Redes falham, entregas são repetidas, eventos podem chegar fora de ordem e o consumidor pode ficar indisponível. Por isso, desenvolvimento de webhooks personalizados exige idempotência, validação de assinatura, logs, filas, política de tentativas e reconciliação.
Fundamentos
Três fundamentos para receber webhooks com segurança
Autenticidade
Assinaturas e segredos compartilhados ajudam a comprovar que o payload foi enviado pelo fornecedor esperado e não sofreu alteração indevida.
Recuperação
Filas, idempotência e reconciliação protegem a operação contra indisponibilidade, repetição e eventos que chegam fora da ordem ideal.
Framework prático
Como implementar uma integração via webhook
-
1
Catalogue eventos e impacto
Defina quais eventos interessam, qual dado mínimo acompanha cada mensagem e qual ação empresarial deve ocorrer. Um evento de pagamento aprovado tem criticidade diferente de uma atualização informativa.
-
2
Exponha um endpoint receptor restrito
Use HTTPS, valide método e conteúdo recebido, limite tamanho do payload e mantenha a rota dedicada ao processamento de eventos. Evite misturar essa entrada com fluxos de usuário.
-
3
Valide assinatura antes de processar
Siga o mecanismo publicado pelo fornecedor, use o corpo original quando exigido e rejeite mensagens inválidas. A autenticação precisa acontecer antes de qualquer efeito operacional.
-
4
Confirme rápido e processe com resiliência
Registre o evento e responda no prazo esperado pelo fornecedor. Processamentos demorados podem seguir em fila para não provocar novas entregas desnecessárias.
-
5
Reprocesse e reconcilie
Guarde histórico, conte tentativas e disponibilize recuperação para falhas permanentes. Compare periodicamente a origem e o destino em fluxos críticos.
Aplicação prática
Onde webhooks reduzem atraso e consultas desnecessárias
- Confirmação de pagamentos, estornos, cobranças recorrentes e eventos financeiros.
- Webhook WhatsApp Business API para mensagens recebidas e atualizações de entrega.
- Entrada de leads em CRM e disparo de automações comerciais.
- Atualizações de pedidos, estoque e faturamento em ERP ou e-commerce.
- Gatilhos para workflows de n8n com validação e monitoramento.
- Notificações de código, infraestrutura e serviços especializados.
Polling versus entrega por webhook
Comparação ilustrativa do número de chamadas para acompanhar eventos esparsos. Webhooks reduzem tráfego ocioso, mas exigem uma estratégia de recuperação.
Decisão técnica
Webhook complementa a API; não substitui a fonte oficial de estado
Webhook. Entrega um aviso quando algo ocorre. É apropriado para reduzir atraso e evitar consultas repetitivas, mas pode ser repetido ou atrasado por condições de rede.
Consulta por API. Busca o estado atual quando o consumidor precisa dele. É útil para detalhamento, verificação e reconciliação, mesmo em sistemas que já recebem eventos.
Fila interna. Desacopla o recebimento rápido do processamento mais demorado. O endpoint confirma a entrada, e trabalhadores internos executam regras com tentativas controladas.
Métricas e interpretação
Métricas para acompanhar webhooks em produção
Tempo entre evento e processamento. Meça o intervalo desde a ocorrência na origem até a conclusão esperada no destino. A métrica revela atrasos na entrega, na fila e na lógica interna.
Taxa de repetição e reprocessamento. Acompanhe quantos eventos chegam mais de uma vez e quantos precisam de nova tentativa interna. Repetição é esperada; efeito duplicado não é.
Eventos divergentes na reconciliação. Compare periodicamente a API de origem com o estado local. Esse controle encontra mensagens perdidas, expiração de retenção ou falhas que escaparam do fluxo automatizado.
Erros comuns
Erros comuns no desenvolvimento de webhooks
Executar tudo antes de responder. Processamentos longos aumentam timeout e repetição de entrega. Registre o evento, confirme rapidamente e mova trabalho pesado para uma fila quando necessário.
Confiar no payload sem validar assinatura. Uma rota pública pode receber chamadas indevidas. O consumidor precisa comprovar autenticidade antes de produzir efeitos no negócio.
Pressupor entrega única e ordenada. Eventos podem ser repetidos ou chegar fora de ordem. Use identificadores únicos e valide o estado atual antes de aplicar mudanças sensíveis.
Não criar rotina de reconciliação. Mesmo uma implementação robusta pode enfrentar incidentes externos. A conferência periódica protege processos críticos contra perda silenciosa.
Leitura sem ambiguidade
Glossário de siglas e termos técnicos
- Webhook
- Notificação automática enviada para um endpoint quando determinado evento ocorre.
- API — Interface de Programação de Aplicações
- Contrato usado para consultar ou alterar dados em outro sistema. Ler guia relacionado
- Endpoint
- Endereço de uma operação exposta por uma aplicação; no webhook, é a rota que recebe eventos.
- Payload
- Conteúdo de dados transportado na mensagem enviada pelo publicador.
- Polling
- Estratégia de consultar periodicamente um sistema para descobrir se houve mudança.
- Idempotência
- Propriedade que impede uma entrega repetida de produzir efeitos duplicados.
Seu processo depende de webhooks confiáveis?
Implementamos receptores seguros, filas, idempotência, logs e reconciliação para transformar eventos externos em automações sustentáveis.
Conversar sobre integraçãoPerguntas frequentes
FAQ
O que é webhook em termos simples?
Webhook é uma notificação automática enviada por um sistema quando determinado evento ocorre. O consumidor informa um endereço receptor e passa a receber mensagens quando há novidade, como pagamento aprovado, lead criado ou mensagem recebida. Isso reduz consultas repetitivas e permite reação próxima do tempo real.
Qual é a diferença entre API e webhook?
Uma API costuma ser consultada quando uma aplicação precisa ler ou alterar dados em outra. Um webhook percorre o caminho inverso: o sistema de origem envia uma notificação quando algo acontece. As duas abordagens funcionam bem juntas: o webhook avisa, e a API permite consultar detalhes ou confirmar o estado atual.
Por que um webhook pode chegar repetido?
O fornecedor normalmente repete a entrega quando não recebe confirmação no prazo esperado ou quando ocorre falha de rede. Essa repetição é desejável porque reduz perda de eventos. O consumidor deve implementar idempotência: reconhecer o identificador já processado e impedir que o mesmo pagamento, pedido ou mensagem produza efeitos duplicados.
Como verificar se um webhook é verdadeiro?
Use o mecanismo de assinatura documentado pelo fornecedor. Em geral, o publicador calcula uma assinatura a partir do payload e de um segredo compartilhado; o receptor recalcula e compara o valor antes de processar. Também é necessário usar HTTPS, proteger segredos e rejeitar mensagens fora do formato esperado.
Webhooks eliminam a necessidade de reconciliação?
Não. Webhooks reduzem atraso e tráfego ocioso, mas dependem de rede, disponibilidade e retenção do fornecedor. Processos críticos devem comparar periodicamente o estado local com a fonte oficial por API. A reconciliação localiza eventos ausentes, divergências e falhas que não geraram alerta suficiente.
Aprofundamento
Referências
Livros
Designing Event-Driven Systems
Ben Stopford. Fundamentos de arquitetura orientada a eventos e fluxos assíncronos.
Enterprise Integration Patterns
Gregor Hohpe e Bobby Woolf. Vocabulário e padrões para mensagens, consumidores e recuperação de falhas.