técnico · resposta com fontes
Webhook de e-mail: definição e implementação técnica
Um webhook de e-mail é um callback HTTP disparado por um provedor de serviço de e-mail para notificar um servidor de destino sobre eventos específicos. Em vez de a aplicação consultar uma API periodicamente em busca de atualizações de status, o provedor envia um payload JSON ou XML para uma URL predefinida logo depois que o evento acontece, como uma falha de entrega ou um clique em link.
Funcionamento técnico
Quando um evento acontece, o provedor de e-mail gera uma requisição HTTP POST. Essa requisição contém um payload com os metadados do evento, incluindo o ID da mensagem, o endereço do destinatário e o timestamp. O servidor receptor precisa escutar em um endpoint público, validar a requisição recebida e retornar uma resposta 200 OK para confirmar o recebimento. Se o servidor retornar um erro, o provedor pode tentar a entrega novamente usando uma estratégia de backoff exponencial.
Importância para remetentes
Os webhooks são fundamentais para manter a reputação do remetente. Ao receber notificações em tempo real de hard bounces ou reclamações de spam, os desenvolvedores podem remover automaticamente os endereços inválidos das listas. Isso evita envios repetidos para caixas postais inexistentes, um dos principais sinais que os ISPs usam para classificar remetentes como de baixa qualidade. Reagir rapidamente a esses sinais garante taxas de entregabilidade mais altas no geral.
Considerações operacionais
Falhas comuns incluem erros de timeout quando o servidor receptor processa o payload de forma síncrona. Para evitar isso, implemente uma arquitetura assíncrona, na qual o webhook é recebido, colocado em uma fila em um sistema como Redis ou RabbitMQ e confirmado imediatamente. Além disso, a segurança é essencial: os servidores devem verificar a assinatura do provedor ou conferir o IP de origem para evitar notificações de eventos falsificadas.
Exemplo concreto de implementação
Um fluxo típico envolve configurar uma URL em um provedor como o Resend ou o Amazon SES. Quando um usuário clica em um link de um e-mail, o provedor envia uma requisição POST para /webhooks/email com um corpo como { event: click, email: user@example.com, link: https://site.com/offer }. A aplicação então atualiza o registro do usuário no banco de dados para marcar a campanha como bem-sucedida.
Integração com ferramentas
Configurar webhooks exige uma URL pública e uma forma de testar os payloads. Os desenvolvedores podem usar o SendHQ ou suas ferramentas gratuitas (https://sendhq.cc/tools) para atender aos requisitos técnicos da infraestrutura de e-mail e garantir que a configuração siga os padrões do setor.
Perguntas que as equipes fazem
Qual é a diferença entre uma API e um webhook?
Uma API é uma requisição feita pelo cliente ao servidor para buscar dados. Um webhook é uma requisição feita pelo servidor ao cliente para enviar dados automaticamente quando um evento acontece.
Como proteger um endpoint de webhook de e-mail?
Use tokens secretos no cabeçalho, verifique a assinatura HMAC fornecida pelo serviço de e-mail ou restrinja o tráfego de entrada às faixas de IP específicas do provedor.
O que acontece se meu servidor estiver fora do ar durante um evento de webhook?
A maioria dos provedores profissionais coloca o evento em fila e tenta reenviá-lo várias vezes ao longo de horas ou dias antes de marcá-lo como impossível de entregar.
Fontes primárias
- Resend Documentation — Resend (em inglês)
- Postmark Developer Documentation — Postmark (em inglês)
- Amazon SES Developer Guide — Amazon Web Services (em inglês)