Novidades5 min de leitura
Apresentamos os Webhooks v2
Os Webhooks v2 chegaram: 36 tipos de evento, assinaturas HMAC-SHA256, novas tentativas automáticas e documentação completa para cada payload.
GPorGeorge

Estamos lançando os Webhooks v2, uma reformulação completa da forma como o Emailit entrega notificações de eventos em tempo real às suas aplicações. Com 36 tipos de evento 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 a eventos.
O que há de novo
36 tipos de evento em 9 recursos
Os Webhooks v2 cobrem todos os recursos do Emailit. Você pode assinar exatamente os eventos que importam para você ou usar all_events para receber tudo.
Eventos de e-mail acompanham todo o ciclo de vida da entrega:
Evento | Descrição |
|---|---|
| Aceito para entrega |
| Agendado para entrega futura |
| Entregue ao servidor de e-mail do destinatário |
| Falha permanente (hard bounce) |
| Falha temporária na entrega |
| Falha por causa de um erro específico |
| Aceito e depois rejeitado |
| O destinatário está na lista de supressão |
| Um e-mail recebido foi aceito |
| Reclamação de spam registrada |
| Um link do e-mail foi clicado |
| O conteúdo do e-mail foi carregado (aberto) |
Eventos CRUD para domínios, listas de contatos, inscritos, contatos, templates, supressões, verificações de e-mail e listas de verificação de e-mails, cada um com os eventos .created, .updated e .deleted.
Estrutura consistente de eventos
Todos os payloads de webhook seguem o mesmo formato, o que facilita criar um único handler para todos os eventos:
{
"event_id": "evt_2bH7kNwP5mQaV1sXgIdKe6pZr",
"type": "email.delivered",
"data": {
"object": {
"id": "em_4yM2nTvR8oPcX3uZiKeLg7sB",
"object": "email",
...
}
}
}O event_id identifica cada evento de forma única, type diz 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 o segredo do seu webhook usando HMAC-SHA256. A assinatura é calculada sobre {timestamp}.{rawBody}, para você verificar a autenticidade e o quão recente é a requisição em um único passo.
Cada requisição inclui dois cabeçalhos:
X-Emailit-Signature— o digest hexadecimal HMAC-SHA256X-Emailit-Timestamp— o timestamp Unix usado na assinatura
Recomendamos fortemente usar uma comparação em tempo constante (por exemplo, crypto.timingSafeEqual no Node.js) para evitar ataques de timing e rejeitar requisições com timestamps de mais de alguns minutos para se proteger contra ataques de replay.
Exemplos completos de verificação em Node.js, Python, PHP, Ruby e Go estão na documentação de assinatura da requisição.
Novas tentativas automáticas com backoff exponencial
Se o seu endpoint não responder com um 2xx em até 30 segundos, o Emailit tenta de novo 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 cerca de 41 horas. Depois da última tentativa, o webhook é desativado automaticamente. 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 |
|---|---|
|
|
|
|
| Assinatura HMAC-SHA256 |
| Timestamp Unix usado na assinatura |
Boas práticas
- Responda rápido: retorne um
2xxna hora 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 novas tentativas. Use o
event_idpara eliminar duplicatas. - Verifique as assinaturas: sempre valide o cabeçalho
X-Emailit-Signaturepara confirmar que a requisição veio do Emailit. - Proteja-se contra ataques de replay: confira o
X-Emailit-Timestampe rejeite requisições com mais de alguns minutos.
Documentação completa
Publicamos a documentação completa dos Webhooks v2, com exemplos detalhados de payload e a descrição dos campos dos 36 eventos:
- Introdução: visão geral e funcionamento dos webhooks
- Tipos de evento: a lista completa dos 36 tipos de evento
- Requisições de webhook: formato das requisições, cabeçalhos e política de novas tentativas
- Assinatura da 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 o seu primeiro endpoint de webhook.


