Entwickler · Webhooks

Sieben Events, eine Zustell-Garantie

mandate.issued

Neues Mandat aktiv — mit Scope und Laufzeit.

mandate.revoked

Kill Switch ausgelöst — alle abgeleiteten Tokens sind ab sofort wertlos.

mandate.expiring

Mandat läuft in ≤ 7 Tagen ab (täglicher Sweep, 04:00 UTC).

verification.escalated

Step-up ausgelöst — escalation_id, Aktion, Betrag, Frist.

escalation.decided

Mandant hat entschieden — approved/denied, bei approve mit Token-Referenz.

limit.threshold

80 % des Monatslimits erreicht — proaktive Warnung.

consumption.recorded

Betrag endgültig gebucht — mit Restkontingent.

Signatur prüfen

// 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));
}

Zustell-Semantik

▸ At-least-once: Empfänger müssen idempotent verarbeiten (Event-ID dedupen).
▸ 4 Retries mit Backoff (1 s / 10 s / 60 s / 300 s) bei Nicht-2xx.
▸ Danach Dead Letter Queue — einsehbar und manuell re-deliverbar.
▸ Registrierung: POST /v1/webhooks mit url + events[]; Secret wird einmal angezeigt.