Resumo visual do artigo
O que são webhooks?
Webhooks normalmente enviam uma entrega HTTP quando um evento ocorre. Eles podem reduzir consultas de polling em alguns fluxos, mas não garantem entrega instantânea e não eliminam a necessidade de reprocessamento. O contrato do provedor define evento, payload, resposta esperada e política de tentativa.
Como desenhar uma integração
Comece pelo processo: registre o evento, o sistema de origem, o destino, os campos necessários e o responsável por tratar falhas. Ao criar um lead, por exemplo, a entrega pode alimentar um CRM; o processo de CRM precisa estar definido antes da automação.
No endpoint, valide a assinatura conforme a documentação do provedor, compare o segredo de forma segura, limite o que será aceito e registre apenas o necessário. A documentação do GitHub sobre validação de entregas mostra um padrão de validação de assinatura. A implementação também precisa tratar repetição, timeout, indisponibilidade, ordem de eventos e reprocessamento sem duplicar efeitos.
Entrega confiável
O endpoint deve responder no prazo esperado pelo provedor e separar o recebimento do processamento pesado. Uma fila pode ajudar a absorver picos, mas também precisa de limite, observabilidade e uma política de descarte ou encaminhamento. Guarde um identificador do evento para reconhecer reentregas e torne a operação idempotente: receber o mesmo evento duas vezes não deve criar dois leads, cobrar duas vezes ou disparar duas campanhas.
Defina o que acontece quando a assinatura é inválida, o payload não passa na validação, um campo obrigatório está ausente ou o serviço de destino está indisponível. Registre status, horário, identificador e motivo da falha sem armazenar dados além do necessário. Faça um teste com eventos válidos, inválidos, repetidos e fora de ordem, e documente quem revisa a fila de erro.
Onde usar
Webhooks podem conectar formulários, CRMs, filas e automações de e-mail quando a equipe conhece o contrato de cada serviço. Avalie latência, custo, volume, observabilidade e caminho de retorno. Uma integração por evento não substitui autenticação, autorização, logs, testes e uma rotina para corrigir registros que falharam.
FAQ
O que é um webhook?
É uma entrega HTTP disparada por um evento em um serviço, conforme o contrato do provedor.
Como posso usar webhooks?
Você pode usá-los para integrar serviços e registrar eventos, desde que trate autenticação, repetição, falhas e reprocessamento.
Webhooks são seguros?
A segurança depende da implementação. Valide assinatura e segredo, trate repetição, registre eventos e siga a documentação do provedor.
