Verificare firma HMAC

Ogni webhook in uscita include una firma per confermare che il payload proviene da MailingCore e non e stato alterato.

Formato dell'header

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

• t — timestamp Unix dell'invio
• v1 — HMAC-SHA256 in esadecimale

Algoritmo di verifica

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')
  )
}

Buone pratiche

1. Leggi il raw body senza parsare JSON prima di verificare
2. Rifiuta timestamp troppo vecchi (replay) — tolleranza consigliata ±5 min
3. Usa timingSafeEqual per confrontare le firme
4. Rispondi 200 rapidamente e processa in una coda propria

Payload di esempio

Il corpo JSON include type (nome dell'evento), data (dettagli email o contatto) e metadati del tenant. La struttura esatta dipende dall'evento; consulta il riferimento OpenAPI su /docs-json per lo schema aggiornato.