# 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.

2026-02-26 · George (https://x.com/thegeorge, https://www.linkedin.com/in/jiri-zizka/)

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:

```json
{
  "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](https://emailit.com/docs/webhooks/request-signature).

### 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:

- [Introdução](https://emailit.com/docs/webhooks): visão geral e funcionamento dos webhooks
- [Tipos de evento](https://emailit.com/docs/webhooks/event-types): a lista completa dos 36 tipos de evento
- [Requisições de webhook](https://emailit.com/docs/webhooks/webhook-requests): formato das requisições, cabeçalhos e política de novas tentativas
- [Assinatura da requisição](https://emailit.com/docs/webhooks/request-signature): verificação de assinatura com exemplos de código em 5 linguagens

## Comece agora

Acesse a [documentação de webhooks](https://emailit.com/docs/webhooks) para começar ou vá direto para a [referência da API](https://emailit.com/docs/api-reference/webhooks/create) para criar o seu primeiro endpoint de webhook.

---

Source: https://emailit.com/pt/blog/anunciando-webhooks-v2/
