# Presentamos Webhooks v2

> Webhooks v2 ya está aquí: 36 tipos de eventos, firmas HMAC-SHA256, reintentos automáticos y documentación completa de cada payload.

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

Lanzamos **Webhooks v2**, una renovación completa de la forma en que Emailit envía notificaciones de eventos en tiempo real a tus aplicaciones. Con 36 tipos de eventos repartidos en 9 categorías de recursos, verificación de firmas criptográficas y una sólida política de reintentos, Webhooks v2 te ofrece todo lo que necesitas para crear integraciones fiables basadas en eventos.

## Novedades

### 36 tipos de eventos en 9 recursos

Webhooks v2 abarca todos los recursos de Emailit. Puedes suscribirte exactamente a los eventos que te interesan o usar `all_events` para recibirlos todos.

Los **eventos de email** siguen todo el ciclo de vida de la entrega:

| Evento | Descripción |
| --- | --- |
| `email.accepted` | Aceptado para su entrega |
| `email.scheduled` | Programado para entregarse más adelante |
| `email.delivered` | Entregado al servidor de correo del destinatario |
| `email.bounced` | Falló de forma permanente (rebote duro) |
| `email.attempted` | Fallo temporal de entrega |
| `email.failed` | Falló por un error concreto |
| `email.rejected` | Aceptado y luego rechazado |
| `email.suppressed` | El destinatario está en la lista de direcciones bloqueadas |
| `email.received` | Se aceptó un email entrante |
| `email.complained` | Queja de spam registrada |
| `email.clicked` | Se hizo clic en un enlace del email |
| `email.loaded` | Se cargó el contenido del email (apertura) |

**Eventos CRUD** para dominios, listas de contactos, suscriptores, contactos, plantillas, direcciones bloqueadas, verificaciones de emails y listas de verificación de emails, cada uno con sus eventos `.created`, `.updated` y `.deleted`.

### Estructura de eventos uniforme

Cada payload de webhook sigue la misma estructura, lo que facilita crear un único manejador para todos los eventos:

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

`event_id` identifica de forma única cada evento, `type` te indica qué ha ocurrido y `data.object` contiene el recurso completo tal como estaba en el momento del evento.

### Verificación de firma HMAC-SHA256

Cada petición de webhook se firma con HMAC-SHA256 usando el secreto de tu webhook. La firma se calcula sobre `{timestamp}.{rawBody}`, así que puedes comprobar tanto la autenticidad como la vigencia de la petición en un solo paso.

Cada petición incluye dos cabeceras:

- `X-Emailit-Signature` — el digest HMAC-SHA256 en hexadecimal
- `X-Emailit-Timestamp` — la marca de tiempo Unix usada en la firma

Te recomendamos encarecidamente usar una comparación en tiempo constante (p. ej., `crypto.timingSafeEqual` en Node.js) para evitar ataques de temporización, y rechazar las peticiones con marcas de tiempo de hace más de unos minutos para protegerte frente a ataques de repetición.

En la documentación de [firma de peticiones](https://emailit.com/docs/webhooks/request-signature) tienes ejemplos completos de verificación en Node.js, Python, PHP, Ruby y Go.

### Reintentos automáticos con retroceso exponencial

Si tu endpoint no responde con un `2xx` en 30 segundos, Emailit vuelve a intentarlo automáticamente:

| Intento | Espera |
| --- | --- |
| 0 | 5 segundos |
| 1 | 5 minutos |
| 2 | 30 minutos |
| 3 | 2 horas |
| 4 | 5 horas |
| 5 | 10 horas |
| 6 | 24 horas |

En total son 7 intentos a lo largo de unas 41 horas. Tras el último intento, el webhook se desactiva automáticamente. Puedes volver a activarlo desde el panel en cualquier momento.

## Formato de las peticiones

Todas las peticiones de webhook son `POST` con un cuerpo JSON. Cada petición incluye estas cabeceras:

| Cabecera | Descripción |
| --- | --- |
| `Content-Type` | `application/json` |
| `User-Agent` | `Emailit-Webhook/1.0` |
| `X-Emailit-Signature` | Firma HMAC-SHA256 |
| `X-Emailit-Timestamp` | Marca de tiempo Unix usada en la firma |

## Buenas prácticas

- **Responde rápido** — Devuelve un `2xx` de inmediato y procesa el payload de forma asíncrona en una tarea en segundo plano.
- **Gestiona los duplicados** — El mismo evento puede entregarse más de una vez durante los reintentos. Usa `event_id` para descartar duplicados.
- **Verifica las firmas** — Valida siempre la cabecera `X-Emailit-Signature` para confirmar que la petición procede de Emailit.
- **Protégete frente a ataques de repetición** — Comprueba `X-Emailit-Timestamp` y rechaza las peticiones con más de unos minutos de antigüedad.

## Documentación completa

Hemos publicado la documentación completa de Webhooks v2, con ejemplos detallados de payloads y descripciones de los campos de los 36 eventos:

- [Introducción](https://emailit.com/docs/webhooks) — Descripción general y cómo funcionan los webhooks
- [Tipos de eventos](https://emailit.com/docs/webhooks/event-types) — Lista completa de los 36 tipos de eventos
- [Peticiones de webhook](https://emailit.com/docs/webhooks/webhook-requests) — Formato de las peticiones, cabeceras y política de reintentos
- [Firma de peticiones](https://emailit.com/docs/webhooks/request-signature) — Verificación de firmas con ejemplos de código en 5 lenguajes

## Empieza ya

Consulta la [documentación de webhooks](https://emailit.com/docs/webhooks) para empezar o ve directamente a la [referencia de la API](https://emailit.com/docs/api-reference/webhooks/create) para crear tu primer endpoint de webhook.

---

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