Help Developers
Receiving webhooks
Each delivery is a POST to your endpoint with these headers:
Substratal-Event-Id: wev_01JAGD4E5F6G7H8J9K011M2N30
Substratal-Event-Type: access.revoked
Substratal-Delivery-Id: dlv_01JAGM1N2P3Q4R5S6T7V8V9W0X
Substratal-Delivery-Attempt: 1
Substratal-Signature: t=1730649761,v1=5257a869…
Verify the signature
v1 is HMAC-SHA256(signing_secret, "{t}.{raw_request_body}"), hex-encoded. Sign the exact raw bytes you received, not re-serialized JSON. Reject the delivery if t is more than five minutes old. Every retry is signed fresh, so a long-retrying delivery still passes.
import crypto from "node:crypto";
function verify(rawBody, header, secret) {
const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
if (Math.abs(Date.now() / 1000 - Number(parts.t)) > 300) return false;
const expected = crypto.createHmac("sha256", secret).update(`${parts.t}.${rawBody}`).digest("hex");
return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}
Required subscriptions
Every Application must subscribe to access.revoked and role.removed, and end the affected session as soon as one arrives. A short-lived token alone doesn't meet the immediate-revocation requirement.
Payload version
A subscription's payload version (api_version, a date such as 2026-10-05) fixes the shape of the payloads it receives. It's separate from the Substratal-Version header. Move a subscription forward deliberately, from Add / edit webhook.
Debugging deliveries
Webhook — Deliveries shows every attempt with its status code and timing. You can Redeliver any attempt or Send test at any time. A failed delivery is retried 5 more times over about 14 hours (+1 min, +5 min, +30 min, +2 h, +12 h). After 3 consecutive deliveries exhaust their retries, the subscription is marked unhealthy but still receives events. After 5 days unhealthy it's disabled: delivery stops and the owner is emailed. Re-enabling it doesn't backfill the events it missed, so redeliver them or reconcile through the API.
Screens in this guide
WHK-01 · Webhooks WHK-02 · Add / edit webhook WHK-03 · Webhook — Deliveries WHK-04 · Delivery detail