Developers · webhooks
7 events, one delivery guarantee
mandate.issuedNew mandate active — with scope and validity period.
mandate.revokedKill switch triggered — every derived token is worthless from this moment on.
mandate.expiringMandate expires in ≤ 7 days (daily sweep, 04:00 UTC).
verification.escalatedStep-up triggered — escalation_id, action, amount, deadline.
escalation.decidedThe principal has decided — approved/denied; on approve with a token reference.
limit.threshold80% of the monthly limit reached — a proactive warning.
consumption.recordedAmount finally booked — with the remaining allowance.
Verifying the signature
// Header: X-Mandact-Signature: sha256=<hex>
import crypto from "node:crypto";
function verifySignature(rawBody: string, header: string, secret: string) {
const expected = "sha256=" + crypto
.createHmac("sha256", secret).update(rawBody).digest("hex");
return crypto.timingSafeEqual(Buffer.from(header), Buffer.from(expected));
}Delivery semantics
- ▸ At-least-once: receivers must process idempotently (deduplicate by event ID).
- ▸ 4 retries with backoff (1 s / 10 s / 60 s / 300 s) on any non-2xx response.
- ▸ After that, a dead letter queue — inspectable and manually redeliverable.
- ▸ Registration: POST /v1/webhooks with url + events[]; the secret is shown once.