Verify webhook signatures
Verify every notification before treating its contents as trusted input. Use the endpoint’s signing secret and the original HTTP request body.
Signature header
Stello-Signature: t=1756640000,v1=<hex>[,v1=<hex>]Compute HMAC-SHA256 over the timestamp, a period and the raw body. Preserve the original bytes, check a five-minute timestamp tolerance and compare the signature in constant time.
Node.js verification example
import { createHmac, timingSafeEqual } from 'node:crypto';
const TOLERANCE_SECONDS = 300;
export function verify(rawBody: string, header: string, secret: string): boolean {
// "t=1756640000,v1=<hex>,v1=<hex>"
const parts = header.split(',').map((p) => p.trim());
const timestamp = parts.find((p) => p.startsWith('t='))?.slice(2);
const signatures = parts.filter((p) => p.startsWith('v1=')).map((p) => p.slice(3));
if (!timestamp || signatures.length === 0) return false;
// Reject anything too old. The timestamp is inside the signed material, so a
// captured delivery cannot be replayed later with a fresh t.
const age = Math.abs(Math.floor(Date.now() / 1000) - Number(timestamp));
if (!Number.isFinite(age) || age > TOLERANCE_SECONDS) return false;
const expected = createHmac('sha256', secret)
.update(`${timestamp}.${rawBody}`)
.digest('hex');
// ANY signature matching is a pass. During the 24 hours after a secret
// rotation we sign with both the new and the old key, which is what lets you
// paste the new secret in whenever you like with nothing failing either side.
// Comparing only signatures[0] works today and breaks silently a year from
// now, on the afternoon somebody rotates.
return signatures.some((candidate) => {
const a = Buffer.from(candidate, 'hex');
const b = Buffer.from(expected, 'hex');
return a.length === b.length && timingSafeEqual(a, b);
});
}
Mount raw-body middleware before JSON middleware on the webhook route. Parsing and serializing the JSON can change the bytes and invalidate the signature.
Rotation
More than one v1 signature can be present. Accept any valid signature. During the 24-hour rotation window, Stello signs with the new and previous secrets. Update your stored secret promptly and retire the old value after the overlap.
Other headers
| Header | Meaning |
|---|---|
Stello-Event-Type | Same occurrence type as the body |
Stello-Event-Id | Occurrence ID shared across endpoints and retries |
Stello-Delivery-Id | Delivery record ID stable across automatic retries. Manual redelivery creates a new record |
Use the occurrence ID for deduplication and quote the delivery ID when asking for support.