API reference
Webhooks
Get a signed POST when a generation closes, and verify the HMAC signature.
Manage webhooks#
All need a bearer token.
| Method | Path | Does |
|---|---|---|
GET | /v1/me/webhooks | List your webhooks |
POST | /v1/me/webhooks | Add a webhook. The response includes the secret used to sign deliveries |
DELETE | /v1/me/webhooks | Remove 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.