Saltar al contenido
Docs

Guía práctica

Verificar las firmas de los webhooks

Comprueba que las peticiones de webhook vienen de Emailit verificando la firma HMAC-SHA256 y la marca de tiempo, con código para Node.js, Python, PHP, Ruby, Go y Laravel.

Actualizado el 1 oct 2026

Cualquiera que conozca la URL de tu webhook puede enviarle peticiones. Cada petición de Emailit se firma con el secreto de tu webhook, así que verificar la firma demuestra que la petición viene de Emailit y que no se ha modificado por el camino. Comprobar la marca de tiempo impide, además, que se reutilicen peticiones antiguas. Haz ambas cosas antes de actuar sobre cualquier evento.

Cómo funciona la firma

Cada webhook tiene su propio secreto: whsec_ seguido de 64 caracteres hexadecimales. Lo ves una sola vez, al crear el webhook o restablecer el secreto, y Obtener un webhook lo devuelve.

En cada petición, Emailit:

  1. Toma la hora Unix actual en segundos, por ejemplo 1790846045, y la envía en X-Emailit-Timestamp.
  2. Construye la cadena {timestamp}.{raw body}: la marca de tiempo, un punto y los bytes exactos del cuerpo de la petición.
  3. Calcula el HMAC-SHA256 de esa cadena con el secreto completo, incluido whsec_, como clave.
  4. Envía el resultado, codificado en hexadecimal y en minúsculas, en X-Emailit-Signature.

Para verificarla, tu endpoint repite los pasos 2 y 3 con el cuerpo en bruto que recibió y compara su resultado con la cabecera mediante una comparación en tiempo constante. Después comprueba que la marca de tiempo es reciente. Te recomendamos una tolerancia de 5 minutos (300 segundos). Cada reintento se vuelve a firmar con una marca de tiempo nueva, así que un margen de 5 minutos no rechaza los reintentos.

Verificar las peticiones

Cada ejemplo lee el cuerpo en bruto, rechaza con 401 las peticiones sin firma, con una firma antigua o con una firma incorrecta, y solo entonces analiza el array JSON.

server.js
import crypto from 'node:crypto';
import express from 'express';

const app = express();
const SECRET = process.env.EMAILIT_WEBHOOK_SECRET; // full value, including whsec_
const TOLERANCE_SECONDS = 300;

export function verifyEmailitSignature(rawBody, signature, timestamp) {
  if (!signature || !timestamp) return false;

  const age = Math.abs(Math.floor(Date.now() / 1000) - Number(timestamp));
  if (!(age <= TOLERANCE_SECONDS)) return false; // also rejects non-numeric timestamps

  const expected = crypto
    .createHmac('sha256', SECRET)
    .update(`${timestamp}.`)
    .update(rawBody) // a Buffer with the exact bytes received
    .digest('hex');

  const a = Buffer.from(expected);
  const b = Buffer.from(signature);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

// express.raw() keeps the body as a Buffer. Don't run express.json() on this route.
app.post('/webhooks/emailit', express.raw({ type: 'application/json' }), (req, res) => {
  const valid = verifyEmailitSignature(
    req.body,
    req.get('X-Emailit-Signature'),
    req.get('X-Emailit-Timestamp'),
  );
  if (!valid) return res.status(401).send('Invalid signature');

  const events = JSON.parse(req.body.toString('utf8'));
  // Queue the events for processing, then acknowledge.
  res.sendStatus(204);
});

app.listen(3000);

En Laravel, las rutas de routes/api.php no se comprueban con tokens CSRF y reciben el prefijo /api, así que la URL del ejemplo es https://acme.com/api/webhooks/emailit. Si registras la ruta en routes/web.php, exclúyela de la verificación CSRF o Laravel rechazará las peticiones de Emailit con 419.

Probar tu verificación

Comprueba tu función con este ejemplo conocido antes de desplegar. Llama directamente a la parte del HMAC, porque la marca de tiempo está en el pasado y no supera la comprobación de 5 minutos.

Entrada Valor
Secreto whsec_4f2a9c1e7b3d5a8f0e6c2b9d4a7f1e3c5b8d0a2f6e9c3b7d1a5f8e2c4b6d9a0f
Marca de tiempo 1790846045
Firma esperada 7242b580f77ec488f8ac21b57f092e3db61a431694f13074c7b4c85a4dd04be3

Cuerpo en bruto, exactamente como aparece, sin salto de línea al final:

JSON
[{"event_id":"evt_2xGk7Nq1VbD5sR8tLmW3eYhC6aP","type":"email.delivered"}]

Después, usa Send test en el webhook para confirmar que tu endpoint desplegado acepta una petición firmada real. Consulta Configurar un webhook.

Errores habituales

  • Analizar antes de verificar. Los frameworks que analizan el JSON automáticamente (express.json(), request.json en Flask, los params de Rails) te dan un objeto, no los bytes que firmó Emailit. Lee el cuerpo en bruto en la ruta del webhook.
  • Volver a serializar el JSON. JSON.stringify(req.body) o json.dumps(data) generan espacios, orden de claves o escapes distintos, así que el HMAC no coincidirá. Calcula siempre el hash del cuerpo exactamente como se recibió.
  • Modificar el secreto. Usa el valor completo, incluido whsec_, como texto plano. No quites el prefijo ni lo decodifiques como hexadecimal o Base64.
  • Firmar la cadena equivocada. La entrada es la marca de tiempo, un punto y después el cuerpo. Si firmas solo el cuerpo o unes las partes con otro separador, la verificación falla.
  • Usar == para comparar. Usa una función de tiempo constante como crypto.timingSafeEqual, hmac.compare_digest, hash_equals, Rack::Utils.secure_compare o hmac.Equal.
  • Un reloj del servidor desajustado. Si el reloj de tu servidor se desvía, las peticiones válidas quedan fuera de la tolerancia. Mantenlo sincronizado con NTP.
  • Un secreto antiguo o que no corresponde. Tras Reset, el secreto anterior deja de funcionar de inmediato, también para los reintentos. Cada webhook tiene su propio secreto, así que dos endpoints no pueden compartir uno.
  • Un middleware que reescribe el cuerpo. Los proxies, las pasarelas de API o la descompresión del cuerpo que cambian los bytes antes de que los vea tu código rompen la firma. Verifica lo más cerca posible de la petición en bruto.

Las peticiones que no superan la verificación reciben un 401 de tu endpoint y se reintentan como cualquier otro fallo, así que, si corriges un secreto mal configurado en unas pocas horas, no pierdes nada.

¿Te ha resultado útil esta página?

Gracias por tu opinión.

Gracias. Leemos todos los mensajes.