Docs

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.

EventSent when
generation.completedThe run reaches done.
generation.failedThe run fails, or it stalls and Encelade ends it.
project.publishedA project goes from unpublished to published.
project.unpublishedA published project is taken down. Its link stops working.
export.completedAn export started through the API is ready to download.
export.failedAn export started through the API fails or is lost (expired).
project.viewedA 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"
  }'
FieldRequiredDescription
urlYesAn https:// URL on the public internet. Private and internal addresses are rejected.
eventsYesOne or more events.
secretNo1–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"
}
FieldDescription
eventgeneration.completed or generation.failed.
runIdThe run. It matches the runId that starting the run returned.
projectPidThe project the run created.
errorOnly on generation.failed. stage is the step the run was on: queued, intake, researching, planning, writing or composing. code is a short reason.
timestampWhen 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 as https://your-instance.com/p/q3-review-ab12?ref=acme. The tag comes back as refTag.
{
  "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"
}
FieldDescription
visitIdThe visit. Each visit sends one event.
refTagThe link's ?ref= tag, up to 64 characters, or null.
startedAtWhen the visit started, in ISO 8601.
endedAtWhen the viewer was last active, in ISO 8601.
durationMsTime spent on the project's pages, in milliseconds.
pagesViewedHow many of the project's pages the viewer saw.
totalPagesHow many pages the project has.
completionpagesViewed 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 2xx status 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 4xx answer 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, timestamp included. Use runId (or jobId, or projectPid), event and timestamp together to skip duplicates. For project.viewed, visitId is enough.
  • Retrying a failed run in the app keeps its runId. Each attempt sends its own event with a new timestamp, so you can get generation.failed twice, or generation.failed and later generation.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.