Verifying signatures

Curviate-Signature: t=1748430900,v1=3a2f1b4c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a

signed_payload = t + "." + <raw request body bytes>
v1             = HMAC_SHA256(secret, signed_payload) as lowercase hex

import { createHmac, timingSafeEqual } from "crypto";
 
/** A Curviate v1 MAC is always 64 lowercase hex characters (SHA-256). */
const HEX_64 = /^[0-9a-f]{64}$/i;
 
/**
 * Verify a Curviate-Signature header.
 *
 * @param rawBody          Raw request body as a UTF-8 string (do NOT parse JSON first)
 * @param signatureHeader  Value of the Curviate-Signature header (e.g. "t=1748430900,v1=abc123...")
 * @param secret           Your webhook signing secret (CURVIATE_WEBHOOK_SECRET)
 * @returns true if the signature is valid and the timestamp is within 5 minutes.
 *          Never throws: every malformed or hostile input returns false.
 */
export function verifyCurviateSignature(
  rawBody: string,
  signatureHeader: string,
  secret: string,
): boolean {
  // 1. Parse the header: t=<unix_seconds>,v1=<hex>
  const parts = Object.fromEntries(
    signatureHeader.split(",").map((p) => p.split("=")),
  );
  const timestamp = parseInt(parts.t ?? "", 10);
  const providedMac = parts.v1 ?? "";
 
  if (!timestamp || !providedMac) return false;
 
  // 2. Reject a malformed MAC BEFORE building any buffer.
  //    This check is not cosmetic. Buffer.from(x, "hex") silently truncates
  //    invalid input, and timingSafeEqual throws when the two buffers differ
  //    in length. Without this guard an unauthenticated caller crashes your
  //    handler by sending "v1=00".
  if (!HEX_64.test(providedMac)) return false;
 
  // 3. Replay-attack guard: reject deliveries older than 5 minutes
  if (Math.abs(Date.now() / 1000 - timestamp) > 300) return false;
 
  // 4. Recompute the expected MAC
  //    signed_payload = `${timestamp}.${rawBody}`
  const signedPayload = `${timestamp}.${rawBody}`;
  const expectedMac = createHmac("sha256", secret)
    .update(signedPayload, "utf8")
    .digest("hex");
 
  // 5. Constant-time comparison (prevents timing attacks).
  //    Both buffers are now guaranteed to be 32 bytes.
  return timingSafeEqual(
    Buffer.from(expectedMac, "hex"),
    Buffer.from(providedMac, "hex"),
  );
}

import { createHmac } from "crypto";
import { verifyCurviateSignature } from "./verify";
import assert from "assert";
 
const secret = "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2";
 
// A delivery body in the exact shape Curviate sends.
const body = JSON.stringify({
  id: "wdl_01J8Z3K9P0Q1R2S3T4V5W6X7Y8",
  webhook_id: "wh_01J8Z3K9P0Q1R2S3T4V5W6X7Y8",
  event: "message.received",
  data: {
    account_id: "acc_01J8Z3K9P0Q1R2S3T4V5W6X7Y8",
    event: "message.received",
    occurred_at: "2026-08-02T10:00:00.000Z",
    text: "hello",
  },
  delivered_at: "2026-08-02T10:00:00.000Z",
});
 
const t = Math.floor(Date.now() / 1000);
const mac = createHmac("sha256", secret).update(`${t}.${body}`, "utf8").digest("hex");
const header = `t=${t},v1=${mac}`;
 
// 1. Genuine delivery: accepted.
assert.strictEqual(verifyCurviateSignature(body, header, secret), true);
 
// 2. One byte changed in the body, same signature: rejected.
const tampered = body.replace("hello", "hell0");
assert.strictEqual(verifyCurviateSignature(tampered, header, secret), false);
 
// 3. Signed with the wrong secret: rejected.
const forged = createHmac("sha256", "not-your-secret")
  .update(`${t}.${body}`, "utf8")
  .digest("hex");
assert.strictEqual(verifyCurviateSignature(body, `t=${t},v1=${forged}`, secret), false);
 
// 4. Malformed MAC: rejected, NOT thrown. A verifier that throws here lets an
//    unauthenticated caller crash your handler with two characters.
assert.strictEqual(verifyCurviateSignature(body, `t=${t},v1=00`, secret), false);
assert.strictEqual(verifyCurviateSignature(body, `t=${t},v1=${"z".repeat(64)}`, secret), false);
assert.strictEqual(verifyCurviateSignature(body, `t=${t},v1=${mac.slice(0, 63)}`, secret), false);
 
console.log("verifier OK: accepts genuine, rejects tampered, forged and malformed");

import hmac
import hashlib
import os
import re
import time
from fastapi import FastAPI, Request, HTTPException
 
app = FastAPI()
 
CURVIATE_WEBHOOK_SECRET = os.environ["CURVIATE_WEBHOOK_SECRET"].encode()
HEX_64 = re.compile(r"^[0-9a-f]{64}$", re.IGNORECASE)
 
@app.post("/webhooks/curviate")
async def handle_webhook(request: Request):
    # Read raw bytes before anything else
    body = await request.body()
    sig  = request.headers.get("curviate-signature", "")
 
    # Parse header: t=<ts>,v1=<mac>
    parts = dict(p.split("=", 1) for p in sig.split(",") if "=" in p)
    provided = parts.get("v1", "")
 
    # Reject a malformed MAC first. compare_digest raises TypeError on a
    # non-ASCII string, so this check keeps hostile input from crashing you.
    if not HEX_64.match(provided):
        raise HTTPException(status_code=400, detail="Invalid signature")
 
    # A non-numeric t would raise ValueError, so parse it defensively
    try:
        ts = int(parts.get("t", ""))
    except ValueError:
        raise HTTPException(status_code=400, detail="Invalid timestamp")
 
    # Replay guard
    if abs(time.time() - ts) > 300:
        raise HTTPException(status_code=400, detail="Invalid timestamp")
 
    # Verify MAC
    signed_payload = f"{ts}.{body.decode('utf-8')}".encode()
    expected = hmac.new(CURVIATE_WEBHOOK_SECRET, signed_payload, hashlib.sha256).hexdigest()
 
    if not hmac.compare_digest(expected, provided):
        raise HTTPException(status_code=400, detail="Invalid signature")
 
    event = await request.json()
    print(f"Verified event: {event['event']} | delivery: {event['id']}")
 
    # Acknowledge, then process asynchronously
    return {"received": True}

import { constructEvent } from "@curviate/sdk";
 
async function handleWebhook(rawBody: string, req: Request) {
  const event = await constructEvent(
    rawBody,
    req.headers["curviate-signature"],
    process.env.CURVIATE_WEBHOOK_SECRET!,
  );
  // event is typed as CurviateEvent, discriminated on event.event
  console.log("Verified event:", event.event);
}

curviate webhook verify \
  --secret "$CURVIATE_WEBHOOK_SECRET" \
  --header "t=1748430900,v1=3a2f1b4c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a" \
  --body body.json \
  --max-age-secs 999999

curl -sS -X POST https://api.curviate.com/v1/webhooks \
  -H "Authorization: Bearer $CURVIATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "messaging",
    "request_url": "https://hooks.example.com/hooks/curviate",
    "account_ids": ["'"$CURVIATE_ACCOUNT_ID"'"],
    "headers": [{ "key": "X-Environment", "value": "production" }]
  }'

curl -X PATCH "https://api.curviate.com/v1/webhooks/wh_01J8Z3K9P0Q1R2S3T4V5W6X7Y8" \
  -H "Authorization: Bearer cvt_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"request_url": "https://hooks.example.com/hooks/curviate?token=NEW_TOKEN"}'