Webhook Signatures

Every outbound webhook from ScaiVault is signed with HMAC-SHA256. Your endpoint must verify the signature before trusting the payload. Without verification, anyone who knows your URL can forge events.

Headers on delivery#

scdoc

X-ScaiVault-Event-Id: evt_01HK7X9Z
X-ScaiVault-Event-Type: secret.rotated
X-ScaiVault-Timestamp: 1714478400
X-ScaiVault-Signature: sha256=3a1e2b0c...
User-Agent: ScaiVault-Webhook/1.0

Timestamp — Unix seconds at dispatch.
Signature — sha256= followed by hex HMAC-SHA256.

What gets signed#

HMAC(secret, "{timestamp}.{raw_body}") — the timestamp, a literal ., and the raw request body bytes. No JSON reparsing, no header normalization.

Verify in Python#

python
import hmac
import hashlib
import time
from fastapi import FastAPI, Request, HTTPException

app = FastAPI()
WEBHOOK_SECRET = os.environ["SCAIVAULT_WEBHOOK_SECRET"].encode()
MAX_AGE_SECONDS = 300

@app.post("/scaivault/webhook")
async def on_event(request: Request):
    timestamp = request.headers.get("X-ScaiVault-Timestamp", "")
    signature_header = request.headers.get("X-ScaiVault-Signature", "")
    if not timestamp or not signature_header.startswith("sha256="):
        raise HTTPException(400, "missing signature")

    # Reject replays
    age = int(time.time()) - int(timestamp)
    if abs(age) > MAX_AGE_SECONDS:
        raise HTTPException(401, "stale signature")

    body = await request.body()
    expected = hmac.new(
        WEBHOOK_SECRET,
        f"{timestamp}.".encode() + body,
        hashlib.sha256,
    ).hexdigest()

    received = signature_header.removeprefix("sha256=")
    if not hmac.compare_digest(expected, received):
        raise HTTPException(401, "bad signature")

    event = await request.json()
    # Now it's safe to trust event["event_type"], event["path"], etc.
    return {"ok": True}

Verify in TypeScript / Node#

typescript
import crypto from "node:crypto";
import { Request, Response } from "express";

const WEBHOOK_SECRET = process.env.SCAIVAULT_WEBHOOK_SECRET!;
const MAX_AGE_SECONDS = 300;

export function verify(req: Request): boolean {
  const timestamp = req.header("X-ScaiVault-Timestamp");
  const sigHeader = req.header("X-ScaiVault-Signature");
  if (!timestamp || !sigHeader?.startsWith("sha256=")) return false;

  const age = Math.floor(Date.now() / 1000) - parseInt(timestamp, 10);
  if (Math.abs(age) > MAX_AGE_SECONDS) return false;

  const rawBody = (req as any).rawBody as Buffer;  // express.raw({type:'*/*'})
  const expected = crypto
    .createHmac("sha256", WEBHOOK_SECRET)
    .update(`${timestamp}.`)
    .update(rawBody)
    .digest("hex");

  const received = sigHeader.slice("sha256=".length);
  try {
    return crypto.timingSafeEqual(
      Buffer.from(expected, "hex"),
      Buffer.from(received, "hex"),
    );
  } catch {
    return false;
  }
}

Two important details for JavaScript:

Use the raw request body, not a re-serialized JSON object. Body parsing rearranges whitespace and breaks the signature.
Use timingSafeEqual to prevent timing attacks.

Verify in curl (for debugging)#

bash
BODY='{"event_type":"test",...}'
TIMESTAMP=1714478400
EXPECTED=$(printf "%s.%s" "$TIMESTAMP" "$BODY" | openssl dgst -sha256 -hmac "$WEBHOOK_SECRET" | awk '{print $2}')
echo "Expected sha256=$EXPECTED"

Compare against what arrived in X-ScaiVault-Signature.

Replay protection#

The X-ScaiVault-Timestamp header plus a max-age check (5 minutes is standard) prevents replay of captured requests. A captured request is only valid for 5 minutes after the dispatch time.

For stronger replay protection, persist X-ScaiVault-Event-Id in a short-TTL store and reject duplicates:

python
if redis.exists(f"seen:{event_id}"):
    return {"ok": True, "duplicate": True}
redis.set(f"seen:{event_id}", "1", ex=600)

Secret rotation#

Each webhook has a secret configured at registration. To rotate:

Generate a new secret.

PATCH the webhook with the new secret and add the old one as previous_secret (kept for 24h):

bash
curl -X PATCH https://scaivault.scailabs.ai/v1/webhooks/wh_abc \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"secret": "new-secret-here", "previous_secret_ttl": "24h"}'

During the overlap, ScaiVault signs with the new secret; your endpoint accepts either the new or old signature.
After the TTL passes, only the new secret is valid.

Your verification code for the overlap:

python
for candidate in [WEBHOOK_SECRET, OLD_WEBHOOK_SECRET]:
    expected = hmac.new(candidate, signing_input, hashlib.sha256).hexdigest()
    if hmac.compare_digest(expected, received):
        break
else:
    raise HTTPException(401, "bad signature")

Common mistakes#

Parsing JSON before verifying. Many frameworks re-serialize the body after parsing. You must sign and verify the raw bytes.
No timestamp check. Without one, a captured webhook is replayable forever.
String comparison for signatures. Use a constant-time compare (hmac.compare_digest in Python, timingSafeEqual in Node).
Leaking signature details. Don't respond with "bad signature expected X got Y" — that helps an attacker. A plain 401 is fine.

What's next#

Events and Webhooks — event catalog and delivery semantics.
Webhooks Reference — management endpoints.