Skip to Content
WebhooksVerify signatures

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

HeaderMeaning
Stello-Event-TypeSame occurrence type as the body
Stello-Event-IdOccurrence ID shared across endpoints and retries
Stello-Delivery-IdDelivery 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.

Build a receiver with durable processing.