Pular para o conteúdo

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.

GPor

Apresentamos os Webhooks v2

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

email.accepted

Aceito para entrega

email.scheduled

Agendado para entrega futura

email.delivered

Entregue ao servidor de e-mail do destinatário

email.bounced

Falha permanente (hard bounce)

email.attempted

Falha temporária na entrega

email.failed

Falha por causa de um erro específico

email.rejected

Aceito e depois rejeitado

email.suppressed

O destinatário está na lista de supressão

email.received

Um e-mail recebido foi aceito

email.complained

Reclamação de spam registrada

email.clicked

Um link do e-mail foi clicado

email.loaded

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-SHA256
  • X-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

Content-Type

application/json

User-Agent

Emailit-Webhook/1.0

X-Emailit-Signature

Assinatura HMAC-SHA256

X-Emailit-Timestamp

Timestamp Unix usado na assinatura

Boas práticas

  • Responda rápido: retorne um 2xx na 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_id para eliminar duplicatas.
  • Verifique as assinaturas: sempre valide o cabeçalho X-Emailit-Signature para confirmar que a requisição veio do Emailit.
  • Proteja-se contra ataques de replay: confira o X-Emailit-Timestamp e 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:

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.

Compartilhar

Experimente o que você acabou de ler.

3.000 e-⁠mails por mês grátis. Sem cartão de crédito.

3.000 e-⁠mails por mês grátis · Sem cartão de crédito