Anunciando Webhooks v2

Estamos lançando os Webhooks v2, uma reformulação completa de como o Emailit entrega notificações de eventos em tempo real para suas aplicações. Com 36 tipos de eventos distribuídos em 9 categorias de recursos, verificação de assinatura criptográfica e uma política robusta de novas tentativas, os Webhooks v2 oferecem tudo o que você precisa para construir integrações confiáveis e orientadas por eventos.

O que há de novo

36 tipos de eventos em 9 recursos

Os Webhooks v2 cobrem todos os recursos do Emailit. Você pode se inscrever exatamente nos eventos que importam para você ou usar all_events para receber tudo.

Eventos de email acompanham todo o ciclo de vida da entrega:

Evento	Descrição
email.accepted	Aceito para entrega
email.scheduled	Agendado para entrega futura
email.delivered	Entregue ao servidor de email do destinatário
email.bounced	Falha permanente (bounce definitivo)
email.attempted	Falha temporária na entrega
email.failed	Falhou devido a um erro específico
email.rejected	Aceito e depois rejeitado
email.suppressed	Destinatário está na lista de supressão
email.received	Email recebido foi aceito
email.complained	Reclamação de spam registrada
email.clicked	Um link no email foi clicado
email.loaded	Conteúdo do email foi carregado (aberto)

Eventos CRUD para domínios, audiências, assinantes, contatos, templates, supressões, verificações de email e listas de verificação de email, cada um com eventos .created, .updated e .deleted.

Estrutura consistente de eventos

Cada payload de webhook segue o mesmo formato, facilitando a criação de um único manipulador para todos os eventos:

{
  "event_id": "evt_2bH7kNwP5mQaV1sXgIdKe6pZr",
  "type": "email.delivered",
  "data": {
    "object": {
      "id": "em_4yM2nTvR8oPcX3uZiKeLg7sB",
      "object": "email",
      ...
    }
  }
}

O event_id identifica exclusivamente cada evento, type informa o que aconteceu, e data.object contém o recurso completo no momento do evento.

Verificação de assinatura HMAC-SHA256

Cada requisição de webhook é assinada com seu segredo de webhook usando HMAC-SHA256. A assinatura é calculada sobre {timestamp}.{rawBody}, permitindo verificar autenticidade e atualidade em uma única etapa.

Cada requisição inclui dois cabeçalhos:

• X-Emailit-Signature — o digest hexadecimal HMAC-SHA256
• X-Emailit-Timestamp — o timestamp Unix usado na assinatura

Recomendamos fortemente usar comparação segura contra timing (ex: crypto.timingSafeEqual no Node.js) para prevenir ataques de timing, e rejeitar requisições com timestamps mais antigos que alguns minutos para proteger contra ataques de replay.

Exemplos completos de verificação em Node.js, Python, PHP, Ruby e Go estão disponíveis na documentação de Assinatura de Requisição.

Novas tentativas automáticas com backoff exponencial

Se seu endpoint não responder com um 2xx em 30 segundos, o Emailit tenta novamente automaticamente:

Tentativa	Atraso
0	5 segundos
1	5 minutos
2	30 minutos
3	2 horas
4	5 horas
5	10 horas
6	24 horas

São 7 tentativas no total ao longo de aproximadamente 41 horas. Após a tentativa final, o webhook é automaticamente desabilitado. Você pode reativá-lo pelo painel a qualquer momento.

Formato da requisição

Todas as requisições de webhook são POST com corpo JSON. Cada requisição inclui estes cabeçalhos:

Cabeçalho	Descrição
Content-Type	application/json
User-Agent	Emailit-Webhook/1.0
X-Emailit-Signature	Assinatura HMAC-SHA256
X-Emailit-Timestamp	Timestamp Unix usado na assinatura

Melhores práticas

• Responda rapidamente — Retorne um 2xx imediatamente e processe o payload de forma assíncrona em um job em segundo plano.
• Trate duplicatas — O mesmo evento pode ser entregue mais de uma vez durante as tentativas. Use event_id para desduplicar.
• Verifique assinaturas — Sempre valide o cabeçalho X-Emailit-Signature para confirmar que a requisição veio do Emailit.
• Proteja contra ataques de replay — Verifique o X-Emailit-Timestamp e rejeite requisições mais antigas que alguns minutos.

Documentação completa

Publicamos documentação completa para os Webhooks v2 com exemplos detalhados de payload e descrições de campos para todos os 36 eventos:

• Introdução — Visão geral e como os webhooks funcionam
• Tipos de Eventos — Lista completa de todos os 36 tipos de eventos
• Requisições de Webhook — Formato de requisição, cabeçalhos e política de novas tentativas
• Assinatura de Requisição — Verificação de assinatura com exemplos de código em 5 linguagens

Comece agora

Acesse a documentação de Webhooks para começar, ou vá direto para a Referência da API para criar seu primeiro endpoint de webhook.