Eventos y webhooks

Cada mensaje que envía recibe un ID de mensaje y pasa por una serie de estados a medida que se pone en cola, se entrega, se reintenta o rebota. Puede seguir este proceso en el registro de envíos de la consola, consultarlo con la API o hacer que cada evento se envíe a su propio servidor mediante un webhook.

#Estados de los mensajes

Cada copia por destinatario tiene un estado. Un estado solo avanza: por ejemplo, un mensaje entregado todavía puede pasar a rebotado o con queja, pero nunca vuelve a en cola.

Las aperturas, los clics y las bajas no son estados. Se registran en el mensaje (opened_at, clicked_at, unsubscribed_at) y se envían como eventos de webhook. En el registro de envíos, un mensaje abierto tiene una etiqueta adicional Abierto.

#Tipos de rebote

#El registro de envíos

La pestaña Registro de envíos de un flujo enumera los mensajes de los últimos 30 días con su hora, destinatario, asunto, categoría, origen (API o SMTP) y estado. Puede filtrar por Destinatario, Estado, Origen, Categoría y un intervalo de fechas.

Haga clic en un mensaje para abrir Detalles del mensaje: el estado, el remitente, el asunto, la categoría, las etiquetas, la última respuesta del servidor receptor y la lista de eventos con el código SMTP, la respuesta, el tipo de rebote, el host MX y la IP de cada intento de entrega.

La pestaña Resumen agrega los mismos datos para 7 o 30 días: enviados, tasa de entrega, tasa de rebote, tasa de quejas, aperturas y clics.

#Webhooks

Un webhook envía cada evento a un endpoint HTTPS suyo en el momento en que se produce, de modo que su aplicación pueda, por ejemplo, marcar como no válida la dirección de un usuario tras un rebote permanente.

#Configurar un webhook

1. Abra el flujo y vaya a la pestaña Webhook.
2. En URL de destino, introduzca una URL https:// accesible desde Internet. No se aceptan direcciones privadas ni locales.
3. En Eventos, seleccione los eventos que desea. Todos los eventos están seleccionados de forma predeterminada.
4. Haga clic en Guardar. La primera vez que guarda una URL, se muestra una sola vez el Secreto de firma. Empieza por whsec_. Guárdelo en su servidor.
5. Haga clic en Enviar prueba para enviar un evento test y comprobar que su endpoint responde.

Para obtener un secreto nuevo, haga clic en Restablecer secreto de firma. El secreto anterior deja de funcionar de inmediato. Para dejar de recibir eventos, borre la URL y guarde.

#Eventos

Los destinatarios rechazados por la propia API HTTP se devuelven en el campo rejected de la respuesta de la API y no generan ningún webhook.

#Formato de la solicitud

Cada evento se envía como un POST con un cuerpo JSON:

POST /your/webhook HTTP/1.1
Content-Type: application/json
User-Agent: Yeap-TM-Webhook/1
X-Yeap-Signature: t=1760955304,v1=5f2b9c...e81a

{
  "id": "evt_01JAQ40B2C3D4E5F6G7H8J9K0M",
  "type": "bounced",
  "stream_id": 12,
  "message_id": "01JAQ3Z9V8K4M2N6P7R5S1T0XW",
  "created_at": "2026-10-20T10:15:04+00:00",
  "data": {
    "rcpt": "alice@example.org",
    "smtp_code": 550,
    "smtp_response": "5.1.1 The email account that you tried to reach does not exist",
    "bounce_type": "hard",
    "mx": "mx.example.org"
  }
}

id es único para cada evento: úselo para ignorar duplicados. El contenido de data depende del evento:

#Verificar la firma

El encabezado X-Yeap-Signature tiene el formato t=<timestamp>,v1=<signature>. La firma es el HMAC-SHA256 en hexadecimal de <timestamp>.<raw request body>, usando como clave su secreto de firma completo (incluido whsec_). Para comprobar una solicitud:

1. Lea el cuerpo sin procesar exactamente como se recibió, antes de analizar el JSON.
2. Calcule el HMAC sobre t + "." + body y compárelo con v1 mediante una comparación de tiempo constante.
3. Rechace las solicitudes cuya marca de tiempo tenga más de 5 minutos de antigüedad, para bloquear reenvíos maliciosos (replay).

Python:

import hashlib, hmac, time

def verify(secret: str, header: str, body: bytes, tolerance: int = 300) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    ts, sig = parts.get("t", ""), parts.get("v1", "")
    if not ts.isdigit() or abs(time.time() - int(ts)) > tolerance:
        return False
    expected = hmac.new(secret.encode(), ts.encode() + b"." + body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, sig)

Node.js:

const crypto = require('crypto');

function verify(secret, header, rawBody, tolerance = 300) {
  const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')));
  const ts = Number(parts.t);
  if (!ts || Math.abs(Date.now() / 1000 - ts) > tolerance) return false;
  const expected = crypto.createHmac('sha256', secret).update(`${parts.t}.${rawBody}`).digest('hex');
  const a = Buffer.from(expected);
  const b = Buffer.from(parts.v1 || '');
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

#Respuestas y reintentos

• Responda con cualquier estado 2xx en un plazo de 10 segundos. Cualquier otra cosa se considera un fallo.
• Las entregas fallidas se reintentan con intervalos crecientes, empezando por 1 minuto y aumentando hasta un máximo de 4 horas entre intentos. Los reintentos se detienen 24 horas después del evento.
• Los eventos pueden llegar más de una vez o desordenados. Use el id del evento para omitir duplicados y el estado del mensaje para decidir cuál es el actual.

La tabla Entregas recientes de la pestaña Webhook muestra las últimas 100 entregas con su evento, estado (Pendiente pendiente, Éxito correcta, Reintentando reintentando, Abandonado abandonada), número de intentos, último error y hora del siguiente intento.

#Relacionado

• SMTP y API HTTP
• Supresiones y bajas
• Límites, sandbox y cumplimiento