Webhooks de lifecycle.

Tipos de evento

Suscríbete a eventos concretos o a * (todos). Cada entrega es un POST JSON a tu URL.

Crear el endpoint

La respuesta incluye secret una sola vez. Guárdalo fuera de mailack: con él verificas Mailack-Signature. En el portal, el flujo es el mismo (secret visible al crear).

curl -s -X POST "$MAILACK_API_URL/v1/webhooks" \
  -H "Authorization: Bearer $MAILACK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.suempresa.mx/hooks/mailack",
    "events": ["email.queued","email.sent","email.bounced","email.sealed"],
    "description": "ERP"
  }' | jq .

# Guarda "secret" de la respuesta: solo se muestra una vez.

Mailack-Signature

Cada POST lleva headers Mailack-Event, Mailack-Signature (sha256=<hex> HMAC-SHA256 del body crudo) y Mailack-Webhook-Id. Responde 2xx para marcarlo como éxito.

# Node.js — verificar Mailack-Signature
const crypto = require("crypto");

function verify(secret, rawBody, signatureHeader) {
  const expected = "sha256=" + crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signatureHeader || "")
  );
}

Cuerpo del evento

Forma fija: type, created_at (RFC 3339) y data (mapa con message_id y metadatos del evento). No dependas de campos no documentados.

Probar el endpoint

POST /v1/webhooks/{id}/ping (o el botón Probar del portal) envía un evento sintético para validar URL y firma sin esperar tráfico real.

La entrega es asíncrona y best-effort: un fallo en tu endpoint no revierte el envío ni el sellado NOM-151.