Webhooks

Reciba los eventos en cuanto ocurren, para que su sistema sepa siempre qué pasó con cada mensaje. Verifique cada solicitud con su firma.

Cómo funcionan los webhooks

Registre un endpoint HTTPS en el panel y elija los eventos que debe recibir. Cuando le ocurre algo a un mensaje, MigoSMTP envía a su endpoint una solicitud POST con un cuerpo JSON.

Tipos de evento

Suscríbase solo a los eventos que su sistema necesita. Cada evento incluye el id del mensaje, el destinatario y una marca de tiempo, para poder asociarlo con el mensaje que envió.

Ejemplo de payload

Los payloads son JSON enviados con una solicitud POST. Los valores aquí son solo ejemplos.

{
  "event": "delivered",
  "message_id": "msg_123",
  "recipient": "you@example.com",
  "timestamp": "2026-01-15T10:30:00Z"
}

Verifique la firma

Cualquiera que conozca su URL podría enviarle datos, así que verifique cada solicitud. Calcule un HMAC del cuerpo sin procesar de la solicitud con su secreto de firma y compárelo con el valor de la cabecera de firma mediante una comparación en tiempo constante. Rechace las solicitudes que no coincidan. El nombre de la cabecera y el algoritmo se muestran junto a su secreto de firma en el panel.

const crypto = require("crypto");
function valid(rawBody, received, secret) {
  const expected = crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  const a = Buffer.from(expected), b = Buffer.from(received);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Responda rápido

Devuelva un estado 2xx en cuanto haya guardado el evento y haga el trabajo real después, en una cola. Un endpoint lento o con fallos provoca reintentos y puede retrasar sus otros eventos.

Espere duplicados y eventos desordenados

Las entregas fallidas se reintentan, por lo que un mismo evento puede llegar más de una vez y los eventos pueden llegar desordenados. Use el id del mensaje y el tipo de evento para que su manejador sea idempotente, y use la marca de tiempo del evento en lugar de la hora de llegada.

Pruebe antes de depender de ello

Apunte el endpoint a un inspector de solicitudes o a un túnel hacia su máquina de desarrollo, envíe un mensaje de prueba y confirme que puede verificar la firma con tráfico real.