Docs

API reference

Webhooks

Get a signed POST when a generation closes, and verify the HMAC signature.

Manage webhooks#

All need a bearer token.

MethodPathDoes
GET/v1/me/webhooksList your webhooks
POST/v1/me/webhooksAdd a webhook. The response includes the secret used to sign deliveries
DELETE/v1/me/webhooksRemove a webhook

Store the secret when you create the webhook.

The delivery#

When a generation closes, Forgeus sends a POST to your URL:

Body shape·json
{ "type": "generation.closed", "n": "number", "hash": "string", "null": "boolean", "best": { "id": "string", "fitness": "number", "ret": "number" } }
Header·text
x-forgeus-signature: sha256=<hex HMAC-SHA256 of the raw body, keyed with your webhook secret>

Verify the signature#

Compute the HMAC over the raw body bytes, before parsing JSON, and compare in constant time.

verify-webhook.mjs·js
import { createHmac, timingSafeEqual } from "node:crypto";
import { createServer } from "node:http";

const SECRET = process.env.FORGEUS_WEBHOOK_SECRET;

function valid(raw, header) {
  const expected = "sha256=" + createHmac("sha256", SECRET).update(raw).digest("hex");
  const a = Buffer.from(expected);
  const b = Buffer.from(header ?? "");
  return a.length === b.length && timingSafeEqual(a, b);
}

createServer((req, res) => {
  const chunks = [];
  req.on("data", (c) => chunks.push(c));
  req.on("end", () => {
    const raw = Buffer.concat(chunks);
    if (!valid(raw, req.headers["x-forgeus-signature"])) {
      res.writeHead(401).end();
      return;
    }
    const event = JSON.parse(raw);
    console.log("generation closed", event.n, event.hash, event.null ? "(null)" : "");
    res.writeHead(200).end();
  });
}).listen(8787);

Then fetch the full record with /v1/generations/:n if you need more than the summary.

Paper only. No funds are traded. $FOUS is not launched. Nothing here is financial advice.