Guia de infraestrutura de e-mail
Webhooks de e-mail de entrada: padrões de design e segurança
Use webhooks para processar mensagens de entrada sem construir um fluxo de polling de caixa postal.
Um webhook de e-mail de entrada entrega um evento estruturado à sua aplicação quando uma mensagem chega. O desafio de design está no parsing seguro, na autenticação, na idempotência e no tratamento de novas tentativas sem perder mensagens.
O que isso significa na prática
- Entrega de webhook assinada ou autenticada
- IDs de mensagem para processamento idempotente
- Retenção da mensagem bruta para recuperação
- Processamento assíncrono de anexos e tarefas posteriores
Checklist de implementação
- Valide a origem do webhook antes de fazer o parsing do conteúdo.
- Persista o ID de mensagem do provedor antes de qualquer efeito colateral.
- Coloque em fila o processamento demorado de anexos ou de IA.
- Retorne uma resposta de sucesso rapidamente e tente novamente com segurança em falhas transitórias.
Perguntas que as equipes fazem
Devo processar anexos dentro da requisição do webhook?
Em geral, não. Persista a mensagem e coloque o trabalho com anexos em fila para que a confirmação continue rápida e segura para novas tentativas.
Como tratar webhooks duplicados?
Trate o ID de mensagem do provedor como único e torne idempotentes as operações posteriores.