Webhooks
HMAC-signed notifications for email events.
Webhooks notify your endpoints when mail changes state (received, delivered, bounced, complained). Every delivery is signed (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) |
Verifying the signature
The Sending-Signature: t=<unix>,v1=<hmac> header carries the timestamp and the signature.
Compute HMAC-SHA256(secret, "<t>.<rawBody>") and compare it in a timing-safe way.
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);
}