Webhooks
Notifiche firmate HMAC sugli eventi email.
I webhook notificano i tuoi endpoint quando la posta cambia stato (ricevuta, consegnata, bounce, complaint). Ogni consegna e firmata (HMAC SHA-256).
| GET/POST | /api/v1/webhooks | Elenca o crea un endpoint webhook (secret one-time).(scope: webhooks:read|write) |
| GET/PATCH/DELETE | /api/v1/webhooks/:id | Dettaglio, aggiorna o elimina un webhook.(scope: webhooks:read|write) |
| GET | /api/v1/webhooks/:id/deliveries | Log delle consegne di un webhook.(scope: webhooks:read) |
Verificare la firma
L'header Sending-Signature: t=<unix>,v1=<hmac> contiene timestamp e firma. Calcola
HMAC-SHA256(secret, "<t>.<rawBody>") e confronta in modo timing-safe.
import { createHmac, timingSafeEqual } from "node:crypto";
function verify(rawBody: string, header: string, secret: string): boolean {
const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
const expected = createHmac("sha256", secret).update(`${parts.t}.${rawBody}`).digest("hex");
const a = Buffer.from(expected);
const b = Buffer.from(parts.v1 ?? "");
return a.length === b.length && timingSafeEqual(a, b);
}