Change feed and webhooks | Living Brain

Two ways to find out what changed: poll the change feed, or subscribe to webhooks. Most integrations use webhooks for latency and the feed for reconciliation.

The change feed

Every meaningful mutation emits an event with an action:

created · updated · renamed · merged · split · archived · restored · recovered · routed

1 for await (const ev of await client.workspace.changes({ brainId, since: lastSyncedAt })) {
2   console.log(ev.action, ev.pageId, ev.fromVersion, "→", ev.toVersion);
3 }

Filter by pageId to watch one page, or unackedOnly to build an inbox.

Acknowledging

1 await client.workspace.ackChange({ brainId, changeId });
2 const { acked } = await client.workspace.ackAll({ brainId });

Acknowledgement is a user-facing read marker, not a delivery receipt. For machine sync, track since yourself — acking is for “the human has seen this.”

Webhooks

1 const { secret, ...sub } = await client.webhooks.create({
2   url: "https://api.example.com/hooks/livingbrain",
3   events: ["brain.page.updated", "brain.change.new", "brain.connection.new"],
4 });
5 // Store `secret` now — it is never returned again.

The signing secret is returned only on creation. If you lose it, delete the subscription and register a new one.

Events

Event	Fires when
`brain.page.updated`	A page’s content or metadata changed
`brain.change.new`	A new change event was recorded
`brain.connection.new`	A new connection was discovered
`brain.brief.ready`	A daily brief finished generating
`brain.import.progress`	A long-running import advanced

Managing subscriptions

1 const subs = await client.webhooks.list();
2 await client.webhooks.update({ id, events: ["brain.brief.ready"] });
3 await client.webhooks.remove({ id });

Listing never includes secrets. Updating a subscription leaves its secret unchanged.

Daily briefs

A brain can generate a scheduled digest. Configure the schedule, or trigger one on demand:

1 await client.brains.updateBriefSettings({
2   brainId,
3   briefSettings: { enabled: true, hourLocal: 8, timezone: "America/New_York" },
4 });
5 const brief = await client.brains.runBrief({ brainId });

Subscribe to brain.brief.ready rather than polling — generation is not instant.