Stop polling. Take the signed push instead.

What arrives at your endpoint

A single JSON POST with four AffixIO headers and a body containing a delivery id, the event name, an ISO-8601 timestamp and a data object. The body is never chunked across requests and never exceeds a few hundred bytes in practice.

Envelope

POST /affix/webhook HTTP/1.1
Host: example.com
Content-Type: application/json
User-Agent: AffixIO-Webhooks/1.0
X-Affix-Event: proof.verified
X-Affix-Timestamp: 1786780800
X-Affix-Delivery-Id: dlv_4f1c9a02b7e35d81c6a4f0d2
X-Affix-Signature: hmac-sha256=6b1f0c...

{
  "delivery_id": "dlv_4f1c9a02b7e35d81c6a4f0d2",
  "event": "proof.verified",
  "created_at": "2026-08-14T21:00:00.000Z",
  "data": {
    "digest": "aeec81911a1cb288c24133ec48abe9f067302b5ac14badeed2c0a609d3c7c5f2",
    "circuit_id": "yesno",
    "proof_id": "prf_9c2d18a6",
    "merkle_root": "1f0b7c...",
    "merkle_leaf_hash": "8d41e2..."
  }
}

The four envelope keys are the same for every event. Only data changes shape, and it only ever carries identifiers and hashes.

The signature scheme, in full

The message is {timestamp}.{raw_body}, the key is the endpoint secret, the function is HMAC-SHA256 and the header carries the lowercase hex digest behind an hmac-sha256= prefix. There is no canonicalisation step and no header list to assemble.

1. Capture the raw body Read the bytes before any JSON parsing. If you re-serialise a parsed object you will change whitespace or key order and the digest will not match.
2. Check the timestamp first Read X-Affix-Timestamp and drop the delivery if it is more than 300 seconds from your own clock. Doing this before the MAC keeps a captured delivery from being replayed at leisure.
3. Recompute the MAC Join the timestamp, a full stop and the raw body, then run HMAC-SHA256 with the endpoint secret as the key.
4. Compare in constant time Strip the prefix from X-Affix-Signature and use a constant time comparison. A plain string equality leaks timing.
5. Deduplicate, then respond fast Treat X-Affix-Delivery-Id as your idempotency key. Return 2xx quickly and do the real work afterwards, because each attempt times out after eight seconds.

Node.js receiver

import express from "express";
import { createHmac, timingSafeEqual } from "node:crypto";

const SECRET = process.env.AFFIX_WEBHOOK_SECRET;
const TOLERANCE_SECONDS = 300;

const app = express();

app.post(
  "/affix/webhook",
  express.raw({ type: "application/json" }),
  (req, res) => {
    const ts = Number(req.get("X-Affix-Timestamp"));
    const provided = (req.get("X-Affix-Signature") ?? "").replace(/^hmac-sha256=/i, "");
    const body = req.body.toString("utf8");

    if (!Number.isFinite(ts) || Math.abs(Date.now() / 1000 - ts) > TOLERANCE_SECONDS) {
      return res.status(400).send("stale");
    }

    const expected = createHmac("sha256", SECRET).update(`${ts}.${body}`).digest("hex");
    const a = Buffer.from(expected, "utf8");
    const b = Buffer.from(provided, "utf8");
    if (a.length !== b.length || !timingSafeEqual(a, b)) {
      return res.status(401).send("bad signature");
    }

    res.status(204).end();
    queue.push(req.get("X-Affix-Delivery-Id"), JSON.parse(body));
  }
);

Python receiver

import hashlib
import hmac
import time

TOLERANCE_SECONDS = 300


def verify(secret: str, headers, raw_body: bytes) -> bool:
    try:
        ts = int(headers["X-Affix-Timestamp"])
    except (KeyError, ValueError):
        return False

    if abs(time.time() - ts) > TOLERANCE_SECONDS:
        return False

    provided = headers.get("X-Affix-Signature", "")
    provided = provided.split("=", 1)[-1].strip().lower()

    message = f"{ts}.".encode() + raw_body
    expected = hmac.new(secret.encode(), message, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, provided)

Both examples appear on the Python page and the browser page in the wider context of calling the API. The rule that matters is the same in every language: hash the timestamp and the bytes you received, not the object you parsed.

Registering and rotating

The Hub webhooks page is the shortest path: sign in, add a label, paste an HTTPS URL, tick the events. The signing secret is shown once, at creation, in the form whsec_ followed by 48 hex characters. Copy it into your receiver's environment then.

The same operations are available over the API when you would rather manage endpoints from code. Authenticate with a Hub session or an API key.

curl -X POST https://api.affix-io.com/api/webhooks \
  -H "Authorization: Bearer $AFFIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "billing-events",
    "url": "https://example.com/affix/webhook",
    "events": ["proof.verified", "proof.spent"]
  }'

Scope follows ownership. An endpoint registered from a Hub session receives events triggered by any key on that account. An endpoint registered with an API key and no session receives events triggered by that key alone. Rotation does not change scope.