Saltar al contenido

Eventos y webhooks

Recibe en tu servidor cada entrega, rebote o queja de Vemudo con webhooks firmados con HMAC, reintentos durante 72 horas y deduplicación.

Por Equipo Vemudo · Actualizado el

Cada email pasa por una serie de eventos: enviado, entregado, rebotado... Puedes consultarlos cuando quieras o recibirlos en tu servidor con webhooks en cuanto ocurren.

Eventos de un email

GET /v1/emails/{id}/events devuelve la línea de eventos de un email (scope read o full). Cada evento tiene su type, su occurredAt y, según el caso, datos adicionales: el tipo de rebote, el tipo de queja o el enlace pulsado. Nunca incluye cuerpos de email ni diagnósticos del servidor del destinatario.

Webhooks

Los webhooks avisan a tu URL mediante una petición POST con un JSON. Estos son los eventos disponibles:

EventoCuándo ocurre
email.sentVemudo entregó el email al proveedor de correo.
email.deliveredEl servidor del destinatario lo aceptó.
email.deferredLa entrega se retrasa; se seguirá intentando.
email.bouncedRebotó. Incluye bounce con type (permanent, transient o undetermined), subType y code.
email.complainedEl destinatario lo marcó como spam. Incluye complaint.feedbackType.
email.suppressedNo se envió porque la dirección estaba en la lista de bajas.
email.rejectedEl proveedor lo rechazó.
email.failedNo se pudo enviar. reason indica el motivo, por ejemplo send_outcome_unknown.
email.cancelledSe canceló antes de enviarse.

Las aperturas y los clics de campañas no generan webhooks: se consultan en el informe de la campaña.

Crear un endpoint

Desde el panel, o por API con una clave full:

bash
curl -X POST https://api.vemudo.com/v1/webhooks \
  -H "Authorization: Bearer $VEMUDO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.tienda.es/webhooks/vemudo",
    "eventTypes": ["email.delivered", "email.bounced"],
    "description": "Producción"
  }'

La respuesta incluye el secreto de firma (whsec_...) una sola vez. Guárdalo: en los listados solo aparece enmascarado.

Reglas:

  • La URL debe ser HTTPS, sin usuario ni contraseña, con puerto 443 o entre 1024 y 65535, y resolver a una dirección IP pública. Si apunta a una red privada, la respuesta es 422 webhook_url_not_allowed.
  • Cada endpoint es del entorno de la clave que lo crea (test o live) y solo recibe eventos de ese entorno.
  • Máximo 10 endpoints por organización y 20 altas por hora.
  • Si no quieres exponer tu servidor para probar, usa una URL de un servicio de depuración de webhooks con una clave test.

Contenido de la petición

json
{
  "createdAt": "2026-11-04T10:42:08.212Z",
  "data": {
    "emailId": "...",
    "from": "Tienda Alba <[email protected]>",
    "occurredAt": "2026-11-04T10:42:08.212Z",
    "tags": { "pedido": "1042" },
    "templateId": null,
    "to": "[email protected]"
  },
  "environment": "live",
  "id": "...",
  "type": "email.delivered"
}

El id del evento es el mismo que la cabecera Vemudo-Event-Id. Las claves del JSON llegan ordenadas alfabéticamente y siempre con el mismo formato en cada reintento.

Cabeceras

CabeceraContenido
Vemudo-Signaturet=<segundos unix>,v1=<firma>
Vemudo-Event-IdIdentificador del evento, único.
Vemudo-Delivery-AttemptNúmero de intento, desde 1.
User-AgentVemudo-Webhooks/1.0
Content-Typeapplication/json

Verificar la firma

La firma es HMAC-SHA256(secreto, t + "." + cuerpoCrudo) en hexadecimal, calculada sobre el cuerpo tal como llega, antes de analizar el JSON. Tras rotar el secreto, durante 24 horas la cabecera lleva dos v1= (el nuevo primero); acepta si coincide cualquiera.

js
const crypto = require('node:crypto');

function verify(rawBody, header, secret) {
  const parts = header.split(',');
  const t = Number(parts.find((p) => p.startsWith('t=')).slice(2));
  if (Math.abs(Date.now() / 1000 - t) > 300) return false;
  const expected = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
  return parts
    .filter((p) => p.startsWith('v1='))
    .some((p) => {
      const got = p.slice(3);
      return (
        got.length === expected.length &&
        crypto.timingSafeEqual(Buffer.from(got), Buffer.from(expected))
      );
    });
}

Rechaza las peticiones con un t de hace más de 5 minutos para evitar repeticiones.

Responder y reintentos

  • Responde con un código 2xx en menos de 10 segundos. Cualquier otra cosa, un fallo de conexión o una redirección (no se siguen) cuenta como fallo.
  • Los fallos se reintentan con esperas crecientes: 1 minuto, 5 minutos, 30 minutos, 2 horas, 5 horas, 10 horas y 12 horas, con una pequeña variación aleatoria. Pasadas 72 horas desde el primer intento, la entrega se da por fallida.
  • Si un endpoint falla durante 72 horas y acumula al menos 10 fallos, Vemudo lo desactiva y avisa por email a los propietarios y administradores. Desde el panel puedes reactivarlo.
  • Una entrega puede llegar más de una vez y no hay garantía de orden entre eventos. Deduplica por Vemudo-Event-Id y no dependas del orden: usa occurredAt.

Rotar el secreto

El panel permite rotar el secreto de un endpoint (hasta 5 veces por hora). Durante 24 horas Vemudo firma con el nuevo y el anterior para que puedas actualizar tu servidor sin perder eventos.

Listar y borrar

bash
curl https://api.vemudo.com/v1/webhooks -H "Authorization: Bearer $VEMUDO_API_KEY"
curl -X DELETE https://api.vemudo.com/v1/webhooks/$ID -H "Authorization: Bearer $VEMUDO_API_KEY"

La lista solo incluye los endpoints del entorno de la clave. Borrar un endpoint borra también sus entregas.