Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

docs(api): document the forge.completed and forge.failed webhook events

nirholas9bb2bf7b5401
diff --git a/docs/api-reference.md b/docs/api-reference.md
index f26624fd6..4b0f70c4e 100644
--- a/docs/api-reference.md
+++ b/docs/api-reference.md
@@ -1350,6 +1350,12 @@ silently.
Poll with `GET /api/forge?job=<job>` — it returns `{ status: "queued" | "done" | "failed", glb_url? }`.
+Signed-in callers can skip the poll loop entirely: register a webhook for
+`forge.completed` and `forge.failed` and the platform POSTs you the finished
+job. Payloads, delivery semantics and a runnable subscribe-then-submit example
+are in
+[docs/developer-platform.md](./developer-platform.md#generation-job-events).
+
A generation that fails mid-flight on one engine is automatically re-dispatched
to the next configured free lane (up to 3 backups); the poll keeps reporting
`status: "running"` with the new `backend` plus a `failover_from` field, so the
diff --git a/docs/developer-platform.md b/docs/developer-platform.md
index aa9f1e6f6..401c5b5a2 100644
--- a/docs/developer-platform.md
+++ b/docs/developer-platform.md
@@ -258,6 +258,78 @@ Event types:
- `agent.created`
- `agent.updated`
- `agent.deleted`
+- `forge.completed`
+- `forge.failed`
+
+### Generation job events
+
+A forge generation is asynchronous and outlives the request that started it: you
+submit to `POST /api/forge`, get a `job_id` back, and the platform finishes the
+job even if the caller disconnects (see
+[forge-background-generation.md](./forge-background-generation.md)). Without a
+push, the only way to learn the outcome is to keep polling
+`GET /api/forge?job=<job_id>`. These two events replace that poll loop.
+
+They are scoped to your account, so they fire for generations made while signed
+in (a session cookie or a bearer token on the submit). Anonymous browser
+generations have no account to deliver to.
+
+`forge.completed` fires from the single completion writer every generation lane
+flows through, which makes it exactly-once per job and independent of how the
+job finished: the free lane, a paid x402 call, or the unattended finalizer that
+picks up an abandoned job all deliver the same event.
+
+```json
+{
+ "id": "3f2b9c40-1a77-4d2e-9c31-8a0e5b7d41aa",
+ "status": "done",
+ "prompt": "a small wooden toy boat with a striped sail",
+ "glb_url": "https://three.ws/cdn/forge/<client>/<id>.glb",
+ "preview_image_url": "https://three.ws/cdn/forge/<client>/<id>.webp",
+ "backend": "trellis_selfhost",
+ "tier": "draft",
+ "path": "image",
+ "size_bytes": 1638400,
+ "latency_ms": 150000
+}
+```
+
+`forge.failed` fires only when a job is genuinely dead. A generation that fails
+on one lane and is automatically redispatched to another is **not** reported
+here: the platform is still working on it, and you get `forge.completed` if the
+retry lands. That is why a failure event can arrive several minutes after the
+lane error itself.
+
+```json
+{
+ "id": "3f2b9c40-1a77-4d2e-9c31-8a0e5b7d41aa",
+ "status": "failed",
+ "prompt": "a small wooden toy boat with a striped sail",
+ "error": "generation timed out after 45 minutes",
+ "backend": "trellis_selfhost",
+ "tier": "draft"
+}
+```
+
+Subscribe to just these two and submit a job:
+
+```bash
+# 1. register the receiver
+curl -s https://three.ws/api/developer/webhooks \
+ -b "__Host-sid=$SID" -H "x-csrf-token: $CSRF" \
+ -H 'content-type: application/json' \
+ -d '{"url":"https://example.com/hooks/forge","events":["forge.completed","forge.failed"],"description":"generation results"}'
+
+# 2. submit a generation; the response returns immediately with a job_id
+curl -s https://three.ws/api/forge \
+ -b "__Host-sid=$SID" \
+ -H 'content-type: application/json' \
+ -d '{"prompt":"a small wooden toy boat with a striped sail","tier":"draft"}'
+```
+
+Verify the signature exactly as for every other event (see
+[Delivery format and signature verification](#delivery-format-and-signature-verification));
+the `forge.*` payloads carry no separate signing scheme.
### GET /api/developer/webhooks
@@ -284,7 +356,7 @@ Response, `200`:
"stats_7d": { "total": 24, "succeeded": 23, "failed": 1, "last_delivery_at": "2026-07-29T20:00:00.000Z" }
}
],
- "event_types": ["avatar.created", "avatar.updated", "avatar.deleted", "avatar.appearance.changed", "agent.created", "agent.updated", "agent.deleted"]
+ "event_types": ["avatar.created", "avatar.updated", "avatar.deleted", "avatar.appearance.changed", "agent.created", "agent.updated", "agent.deleted", "forge.completed", "forge.failed"]
}
```