Webhooks

Subscribe#

A subscription is a URL, a threshold in days, and optionally one pool rather than all of them. Creating it returns a signing secret once — Cleaton stores only what it needs to sign with, so a lost secret is replaced by deleting the subscription and creating another.

The payload#

{
  "type":        "horizon.below_threshold",
  "deliveredAt": "2026-08-21T15:22:30.000Z",
  "alertId":     "al_92b00ecee9fdc929",
  "data": {
    "pool":          "4663:0xbeeff033f34c046626b8d0a041844c5d1a5409dd",
    "symbol":        "steakUSDG/USDG",
    "chainId":       4663,
    "horizonDays":   9,
    "confidence":    0.65,
    "thresholdDays": 14,
    "sample":        false
  }
}

sample is there so a fixture row can never be mistaken for a real one by a handler that acts automatically. It is false on everything published today.

Verifying a delivery#

Every delivery carries an HMAC-SHA256 of the raw body under the subscription secret, in a cleaton-signature: sha256=<hex> header:

const raw = await req.text();
const mac = createHmac("sha256", SECRET).update(raw).digest("hex");
if ("sha256=" + mac !== req.headers.get("cleaton-signature")) return 401;

Compute it over the raw body, before parsing. Re-serialising the JSON changes the bytes and the MAC will not match.

Thresholds are yours. Cleaton does not decide what counts as a worrying horizon, because that depends entirely on the lock period of whatever is reading it — fourteen days is alarming for a thirty-day strategy and irrelevant for a daily one.

Events#

One event fires today; the other three are specified. Treat any of them as a nudge to read rather than as an authenticated fact — the HMAC proves the delivery came from Cleaton, not that the numbers inside it are current. Fetch the attestation and check its signature.

Why there is no downgrade feed#

This does not solve reflexivity — nothing does. It reduces the most tradeable form of it. Cleaton also commits to publishing an estimate of the induced component of outflow, measured against matched unattested controls, even though it undercuts headline accuracy.