Sample documentation page (fictional product, used by the DocsChat demo)

Receiving and verifying webhooks

Nimbus signs every delivery so you can confirm it really came from us.

The signature header

Each request carries a Nimbus-Signature header like t=1727860000,v1=5257a869e7.... The value t is the timestamp and v1 is an HMAC-SHA256 signature.

Verifying a signature

  1. Read the raw request body (do not parse it first).
  2. Build the string {t}.{raw_body}.
  3. Compute an HMAC-SHA256 of that string using your endpoint signing secret (it starts with whsec_).
  4. Compare it to v1 using a constant-time comparison.
  5. Reject the request if the timestamp is older than 5 minutes, to prevent replay attacks.
import { createHmac, timingSafeEqual } from "node:crypto";
function verify(raw, header, secret) {
  const { t, v1 } = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const expected = createHmac("sha256", secret).update(`${t}.${raw}`).digest("hex");
  return Math.abs(Date.now() / 1000 - Number(t)) < 300 && timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}

Responding

Return any 2xx status within 10 seconds to acknowledge a delivery. Do heavy work asynchronously after responding.

Retries

If your endpoint returns a non-2xx status or times out, Nimbus retries with exponential backoff: after 1 minute, 5 minutes, 30 minutes, 2 hours and 12 hours, then gives up after 24 hours and marks the delivery as failed. An endpoint that fails continuously for 3 days is disabled and you receive an email.