Webhooks
Get a request from Encelade when a generation run finishes, a project is published, an export ends or someone views a project, instead of polling.
A webhook sends an HTTPS POST to your URL when a generation run in your workspace finishes, when a project is published or unpublished, when an export started through the API ends, or when someone views a published project. Generation and publish events are sent whether the change happened in the app, through the API or through MCP.
| Event | Sent when |
|---|---|
generation.completed | The run reaches done. |
generation.failed | The run fails, or it stalls and Encelade ends it. |
project.published | A project goes from unpublished to published. |
project.unpublished | A published project is taken down. Its link stops working. |
export.completed | An export started through the API is ready to download. |
export.failed | An export started through the API fails or is lost (expired). |
project.viewed | A visit to a published project ends. See Views. |
A canceled run sends no event. Publishing a project that is already published, or changing only its link password, sends no event. Exports started in the app send no event.
Register a webhook
Create a token
A workspace admin creates an API token with the webhook:write scope, or with no scopes. See Authentication.
Use a token just for webhooks. The webhook stops when its token is revoked or expires, so sharing a token with other code makes it easy to break by accident.
Send your URL
curl -X POST https://your-instance.com/api/public/v1/webhooks \
-H "x-api-key: YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com/encelade-hook",
"events": ["generation.completed", "generation.failed"],
"secret": "YOUR_SIGNING_SECRET"
}'| Field | Required | Description |
|---|---|---|
url | Yes | An https:// URL on the public internet. Private and internal addresses are rejected. |
events | Yes | One or more events. |
secret | No | 1–256 characters. Encelade signs each request with it. You can't read it back or change it later. |
This returns 201 with the webhook's id. A workspace can have up to 20 webhooks.
The request you receive
{
"event": "generation.failed",
"runId": "RUN_ID",
"projectPid": "PROJECT_PID",
"error": { "stage": "writing", "code": "CODE" },
"timestamp": "2026-11-05T14:32:10.512Z"
}| Field | Description |
|---|---|
event | generation.completed or generation.failed. |
runId | The run. It matches the runId that starting the run returned. |
projectPid | The project the run created. |
error | Only on generation.failed. stage is the step the run was on: queued, intake, researching, planning, writing or composing. code is a short reason. |
timestamp | When Encelade sent the event, in ISO 8601. |
A generation request doesn't include the project's name or link. To get them, call GET /api/public/v1/generation/runs/{runId} with a token that has session:read. Its link field opens the project in the editor.
Images can still be loading when generation.completed arrives. Before you
export, poll the run until mediaStatus is settled or skipped.
A project.published or project.unpublished request looks like this:
{
"event": "project.published",
"projectPid": "PROJECT_PID",
"slug": "q3-review-ab12",
"viewerUrl": "https://your-instance.com/p/q3-review-ab12",
"embedUrl": "https://your-instance.com/p/q3-review-ab12/embed",
"timestamp": "2026-11-05T14:32:10.512Z"
}viewerUrl opens the published project and embedUrl goes in an <iframe>. Both are null on project.unpublished. The slug stays the same, so publishing again brings back the same links.
An export.completed request looks like this:
{
"event": "export.completed",
"projectPid": "PROJECT_PID",
"jobId": "JOB_ID",
"format": "pdf",
"url": "FILE_URL",
"timestamp": "2026-11-09T14:32:10.512Z"
}jobId matches the jobId that starting the export returned, and format is pdf or pptx. url is the same file URL that GET /api/public/v1/projects/{pid}/exports/{jobId} returns. Download it promptly.
export.failed has an error instead of url. When the export fails, it is { "code": "failed", "message": "MESSAGE" }. When the export was lost before it finished, it is { "code": "expired" }: start a new export.
Views
project.viewed tells you that someone looked at a published project. It needs a Pro plan or higher.
- Encelade sends one event per visit, 5 to 10 minutes after the visit ends.
- Visits to the project's link and to its embed both count.
- Only recorded visits count. A viewer who declines tracking sends nothing. Opening your own project while signed in sends nothing either.
- The event has no personal data: no name, email, location or device. To tell your own customers apart, give each one a link with a
?ref=tag, such ashttps://your-instance.com/p/q3-review-ab12?ref=acme. The tag comes back asrefTag.
{
"event": "project.viewed",
"projectPid": "PROJECT_PID",
"slug": "q3-review-ab12",
"visitId": "VISIT_ID",
"refTag": "acme",
"startedAt": "2026-11-05T14:20:03.118Z",
"endedAt": "2026-11-05T14:26:41.902Z",
"durationMs": 398784,
"pagesViewed": 9,
"totalPages": 12,
"completion": 75,
"timestamp": "2026-11-05T14:32:10.512Z"
}| Field | Description |
|---|---|
visitId | The visit. Each visit sends one event. |
refTag | The link's ?ref= tag, up to 64 characters, or null. |
startedAt | When the visit started, in ISO 8601. |
endedAt | When the viewer was last active, in ISO 8601. |
durationMs | Time spent on the project's pages, in milliseconds. |
pagesViewed | How many of the project's pages the viewer saw. |
totalPages | How many pages the project has. |
completion | pagesViewed as a percentage of totalPages, from 0 to 100. |
Check the signature
If you set a secret, each request has an X-Webhook-Signature header. It holds the HMAC-SHA256 of the raw request body, keyed with your secret, as lowercase hex.
Compute it over the raw bytes, before you parse the JSON, and compare in constant time.
import crypto from "node:crypto";
function isFromEncelade(rawBody, signature, secret) {
const expected = crypto
.createHmac("sha256", secret)
.update(rawBody)
.digest("hex");
return (
typeof signature === "string" &&
signature.length === expected.length &&
crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))
);
}Delivery and retries
- Answer with any
2xxstatus within 10 seconds. Do slow work after you respond. - If the request fails, times out or gets a
5xx, Encelade tries again after about 1 second and then 2 seconds. That's three attempts in total. - A
4xxanswer is final. Encelade doesn't try again. - Encelade doesn't follow redirects. Register the final URL.
- The same request can arrive more than once. A repeat has the same body,
timestampincluded. UserunId(orjobId, orprojectPid),eventandtimestamptogether to skip duplicates. Forproject.viewed,visitIdis enough. - Retrying a failed run in the app keeps its
runId. Each attempt sends its own event with a newtimestamp, so you can getgeneration.failedtwice, orgeneration.failedand latergeneration.completed, for the same run.
When a webhook stops
A webhook stops sending, without notice, when:
- the token that created it is revoked or expires, or
- the admin who created it leaves the workspace.
To see the webhooks that still send, call GET /api/public/v1/webhooks with a token that has webhook:read. If one is missing, register it again with a current token.
Delete a webhook
curl -X DELETE https://your-instance.com/api/public/v1/webhooks/WEBHOOK_ID \
-H "x-api-key: YOUR_API_TOKEN"This returns 204. See the Webhooks reference for every field and error.