Lifecycle webhooks.

Event types

Subscribe to specific events or * (all). Every delivery is a JSON POST to your URL.

Create the endpoint

The response includes secret exactly once. Store it outside mailack — you use it to verify Mailack-Signature. The portal uses the same flow.

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

Each POST carries Mailack-Event, Mailack-Signature (sha256=<hex> HMAC-SHA256 of the raw body) and Mailack-Webhook-Id. Respond 2xx to mark success.

# 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 || "")
  );
}

Event body

Fixed shape: type, created_at (RFC 3339) and data (map with message_id and event metadata). Do not rely on undocumented fields.

Test the endpoint

POST /v1/webhooks/{id}/ping (or the portal Test button) sends a synthetic event so you can validate URL and signature without waiting for real traffic.

Delivery is async and best-effort: a failure on your side does not roll back send or NOM-151 sealing.