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
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
POST con un JSON. Estos son los eventos disponibles:
email.sent | |
email.delivered | |
email.deferred | |
email.bounced | bounce con type (permanent, transient o undetermined), subType y code. |
email.complained | complaint.feedbackType. |
email.suppressed | |
email.rejected | |
email.failed | reason indica el motivo, por ejemplo send_outcome_unknown. |
email.cancelled |
Crear un endpoint
full:
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"
}'whsec_...) una sola vez. Guárdalo: en los listados solo aparece enmascarado.
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 ( testolive) 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
{
"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"
}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
Vemudo-Signature | t=<segundos unix>,v1=<firma> |
Vemudo-Event-Id | |
Vemudo-Delivery-Attempt | |
User-Agent | Vemudo-Webhooks/1.0 |
Content-Type | application/json |
Verificar la firma
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.
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))
);
});
}t de hace más de 5 minutos para evitar repeticiones.
Responder y reintentos
Responde con un código 2xxen 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-Idy no dependas del orden: usaoccurredAt.
Rotar el secreto
Listar y borrar
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"