Verificar firma HMAC

Cada webhook saliente incluye una firma para que confirmes que el payload proviene de MailingCore y no fue alterado.

Formato del header

X-MailingCore-Signature: t=1719763200,v1=5f7b3c...

• t — timestamp Unix del envio
• v1 — HMAC-SHA256 en hexadecimal

Algoritmo de verificacion

const crypto = require('crypto')

function verifyWebhook(rawBody, signatureHeader, secret) {
  const parts = Object.fromEntries(
    signatureHeader.split(',').map((p) => p.split('='))
  )
  const timestamp = parts.t
  const receivedSig = parts.v1

  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${timestamp}.${rawBody}`)
    .digest('hex')

  return crypto.timingSafeEqual(
    Buffer.from(receivedSig, 'hex'),
    Buffer.from(expected, 'hex')
  )
}

Buenas practicas

1. Lee el raw body sin parsear JSON antes de verificar
2. Rechaza timestamps muy antiguos (replay) — tolerancia recomendada ±5 min
3. Usa timingSafeEqual para comparar firmas
4. Responde 200 rapidamente y procesa en cola propia

Payload de ejemplo

El cuerpo JSON incluye type (nombre del evento), data (detalles del email o contacto) y metadatos del tenant. La estructura exacta depende del evento; consulta la referencia OpenAPI en /docs-json para el esquema actualizado.