> ## Documentation Index
> Fetch the complete documentation index at: https://docs.notifique.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Eventos de Webhook
> Reciba en su servidor notificación cuando el email se envía, entrega, abre, hace clic, falla o se marca como spam.
Con la API usted **pregunta**; con webhooks Notifique **le avisa**. Ideal para marcar pedidos entregados, medir aperturas o suprimir quienes se quejan, sin polling.
## En resumen
* Cada entrega es un **POST** `application/json` a su URL registrada.
* Los eventos `email.*` son **solo email**; WhatsApp usa `message.*`, SMS usa `sms.*`.
* `instanceId` está **vacío** (email no usa instance).
* Habilite **solo** los eventos que necesite su integración.
* Responda **2xx rápido**; el procesamiento pesado va a su cola.
Configuración general: [Webhooks](/es/guides/webhooks/index). Seguridad (firma HMAC): [Seguridad de Webhook](/es/guides/webhooks/seguranca).
***
## Cómo se ve el POST
```json theme={null}
{
"event": "email.delivered",
"workspaceId": "clxx123...",
"instanceId": "",
"timestamp": "2025-02-10T14:30:00.000Z",
"data": {
"emailId": "clxx456...",
"to": "customer@example.com",
"from": "noreply@yourdomain.com",
"status": "DELIVERED",
"deliveredAt": "2025-02-10T14:30:05.000Z"
}
}
```
| Campo | Descripción |
| ------------- | ----------------------------------------------------- |
| `event` | Event name (e.g. `email.delivered`) |
| `workspaceId` | ID del Workspace |
| `instanceId` | Always empty for email |
| `timestamp` | ISO 8601, use para anti-replay |
| `data` | Send fields (`emailId`, `to`, `from`, `status`, etc.) |
Headers: `X-Notifique-Signature`, `X-Notifique-Timestamp`, `X-Workspace-Id`, `X-Webhook-Event`.
***
## Qué debe devolver su servidor
| Respuesta | Efecto |
| ----------------------- | ----------------------------------------- |
| **2xx** en \~10s | Evento entregado; removido de la cola |
| **4xx / 5xx / timeout** | Reintento automático (5 min, 30 min, 2 h) |
¿Procesamiento lento? Devuelva **200** de inmediato y procese en segundo plano. Más de \~10 s cuentan como tiempo de espera y el evento puede volver a enviarse.
Validate `X-Notifique-Signature` and a recent timestamp. Details: [Webhook security](/es/guides/webhooks/seguranca).
***
## Referencia de eventos
Use estos eventos al integrar **e-commerce, ERP o automatización** con email.
### Envío y engagement
| Evento | Cuándo se dispara | Qué hacer con él |
| ------------------ | ---------------------------------------- | ------------------------- |
| `email.sent` | Email accepted and sent | Marcar como enviado |
| `email.delivered` | Provider confirmed inbox delivery | Confirmar entrega |
| `email.opened` | Recipient opened (first tracked open) | Engagement, lead caliente |
| `email.clicked` | Click on a tracked link in the email | Conversión, embudo |
| `email.failed` | Bounce or send error | Limpiar lista, alertar |
| `email.complained` | Marked as spam | Suprimir dirección |
| `email.cancelled` | Scheduled send cancelled before dispatch | Actualizar campaña |
***
## Payload por evento
Cuerpo POST completo. El sobre (`event`, ids, `timestamp`) coincide con el ejemplo anterior; abajo cambia lo de `data`.
```json theme={null}
{
"event": "email.sent",
"workspaceId": "clxx123...",
"instanceId": "",
"timestamp": "2025-02-10T14:29:00.000Z",
"data": {
"emailId": "clxx456...",
"to": "customer@example.com",
"from": "noreply@yourdomain.com",
"subject": "Order confirmation",
"status": "SENT",
"sentAt": "2025-02-10T14:29:00.000Z"
}
}
```
```json theme={null}
{
"event": "email.delivered",
"workspaceId": "clxx123...",
"instanceId": "",
"timestamp": "2025-02-10T14:30:00.000Z",
"data": {
"emailId": "clxx456...",
"to": "customer@example.com",
"from": "noreply@yourdomain.com",
"status": "DELIVERED",
"deliveredAt": "2025-02-10T14:30:05.000Z"
}
}
```
Se dispara en la **primera** apertura rastreada de este envío.
```json theme={null}
{
"event": "email.opened",
"workspaceId": "clxx123...",
"instanceId": "",
"timestamp": "2025-02-10T14:35:00.000Z",
"data": {
"emailId": "clxx456...",
"to": "customer@example.com",
"from": "noreply@yourdomain.com",
"status": "OPENED",
"openedAt": "2025-02-10T14:35:00.000Z"
}
}
```
Se dispara en el **primer** clic en un enlace rastreado (o short link asignado).
```json theme={null}
{
"event": "email.clicked",
"workspaceId": "clxx123...",
"instanceId": "",
"timestamp": "2025-02-10T14:36:00.000Z",
"data": {
"emailId": "clxx456...",
"to": "customer@example.com",
"from": "noreply@yourdomain.com",
"status": "CLICKED",
"clickedAt": "2025-02-10T14:36:00.000Z"
}
}
```
```json theme={null}
{
"event": "email.failed",
"workspaceId": "clxx123...",
"instanceId": "",
"timestamp": "2025-02-10T14:29:30.000Z",
"data": {
"emailId": "clxx456...",
"to": "customer@example.com",
"from": "noreply@yourdomain.com",
"status": "FAILED",
"failedAt": "2025-02-10T14:29:30.000Z",
"errorMessage": "bounce_hard"
}
}
```
Buena práctica: agregue `to` a una lista de supresión al recibir este evento.
```json theme={null}
{
"event": "email.complained",
"workspaceId": "clxx123...",
"instanceId": "",
"timestamp": "2025-02-10T15:00:00.000Z",
"data": {
"emailId": "clxx456...",
"to": "customer@example.com",
"from": "noreply@yourdomain.com",
"status": "COMPLAINED",
"complainedAt": "2025-02-10T15:00:00.000Z"
}
}
```
```json theme={null}
{
"event": "email.cancelled",
"workspaceId": "clxx123...",
"instanceId": "",
"timestamp": "2025-02-10T12:00:00.000Z",
"data": {
"emailId": "clxx456...",
"to": "customer@example.com",
"from": "noreply@yourdomain.com",
"status": "CANCELLED"
}
}
```
***
## Próximos pasos
* [Inicio rápido](/es/emails-api/como-funciona/quick-start): primer envío
* [Introducción](/es/emails-api/como-funciona/introducao): ciclo de estados
* [Alcances](/es/emails-api/como-funciona/escopos-da-api-key): permisos de la clave
* [Webhooks (general guide)](/es/guides/webhooks/index)