HMAC signature verification

Every webhook delivery carries an HMAC-SHA256 signature in the X-Aly-Signatureheader. Verifying it ensures the payload came from Aly, hasn't been tampered with, and isn't a replay older than your tolerance window.

Header format

1X-Aly-Signature: t=1748112900,v1=4f3c9e...d2

t is the unix timestamp (seconds) Aly built the signature.
v1 is the hex-encoded HMAC-SHA256 over t + "." + raw_body.

Verification algorithm

Parse t and the v1 hex digest from the header.
Compute expected = HMAC_SHA256(secret, "${t}.${raw_body}").
Compare v1 to hex(expected) with a constant-time compare.
Reject if |now - t| > 5 minutes.

Use the raw body

Verify against the raw request body bytes, before any JSON parsing or middleware re-serialization. Most signature-mismatch bugs come from a framework that reformats the body before you see it.

Node + Express

1import { createHmac, timingSafeEqual } from "node:crypto";2import express from "express";3 4const SECRET = process.env.ALY_WEBHOOK_SECRET!;5const TOLERANCE_SECONDS = 5 * 60;6 7const app = express();8 9// Capture raw body — Aly verifies against bytes, not re-parsed JSON10app.use(11  express.raw({ type: "application/json", limit: "1mb" })12);13 14app.post("/aly/webhooks", (req, res) => {15  const header = req.get("x-aly-signature") ?? "";16  const parts = Object.fromEntries(17    header.split(",").map((kv) => kv.split("="))18  );19  const t = Number(parts.t);20  const v1 = parts.v1;21 22  if (!t || !v1) return res.status(400).end();23 24  // Reject stale or future signatures25  if (Math.abs(Math.floor(Date.now() / 1000) - t) > TOLERANCE_SECONDS) {26    return res.status(400).end();27  }28 29  const raw = (req.body as Buffer).toString("utf8");30  const expected = createHmac("sha256", SECRET)31    .update(`${t}.${raw}`)32    .digest("hex");33 34  const ok =35    expected.length === v1.length &&36    timingSafeEqual(Buffer.from(expected), Buffer.from(v1));37  if (!ok) return res.status(400).end();38 39  const event = JSON.parse(raw);40  // ... enqueue event.id for processing ...41  res.status(200).end();42});

Python + Flask

1import hmac, hashlib, time2from flask import Flask, request, abort3 4SECRET = "whsec_..."  # from registration5TOLERANCE = 5 * 606 7app = Flask(__name__)8 9@app.post("/aly/webhooks")10def webhook():11    header = request.headers.get("X-Aly-Signature", "")12    parts = dict(p.split("=", 1) for p in header.split(",") if "=" in p)13    try:14        t = int(parts["t"])15        v1 = parts["v1"]16    except (KeyError, ValueError):17        abort(400)18 19    if abs(int(time.time()) - t) > TOLERANCE:20        abort(400)21 22    raw = request.get_data()23    mac = hmac.new(SECRET.encode(), f"{t}.".encode() + raw, hashlib.sha256)24    if not hmac.compare_digest(mac.hexdigest(), v1):25        abort(400)26 27    event = request.get_json(force=True)28    # ... enqueue event["id"] for processing ...29    return "", 200

Common failure modes

Body mutated by a middleware — biggest cause. Capture raw bytes before JSON parsing.
Wrong secret — rotated, or pulled from a different env. Rotate again to confirm.
Clock skew — receiver behind NTP. Sync, or widen the tolerance.
Encoding — read body as bytes, hash as bytes. UTF-8 surrogates in product names trip naive string handling.

Replay protection

The timestamp window prevents replays older than 5 minutes. To defend against in-window replay (e.g. an attacker who saw a delivery seconds ago), track event.id in a short-lived set and reject duplicates.

Was this page helpful?