Trail and webhook
The per-record trail of flags, fixes, approvals, overrides and the finish: event types, the dashboard timeline and JSON export, and the signed immersive.record.finished webhook.
While a record is open, the SDK keeps a trail of what happens to it. When the person finishes, Baseera sends your server the whole trail as a signed webhook. In the dashboard it is a timeline per record.
Event types
| Type | Timeline label | When | Data |
|---|---|---|---|
started | Immersive mode started | The record opened. | title? |
check_raised | Check raised | A check started failing. | id, severity, message, fields |
check_resolved | Check resolved | A check started passing. | id, severity, message, fields |
draft_proposed | Draft proposed | A draft appeared in a field. | field, reason, value |
draft_approved | Draft approved | The person approved a draft. | field, reason, value, previous |
draft_rejected | Draft rejected | The person rejected it, or it was replaced or the record closed. | field, reason |
acknowledged | Acknowledged | The person dismissed a warning or info. | id, severity, message, fields |
signal | Signal from the app | Your UI sent a signal. | name, signalData? |
override | Override with a reason | The person finished with blocking checks open. | reason, checks |
finished | Finished | The finish was recorded. | receipt, openBlocking |
Each event has a source, shown in the timeline: the review panel (panel), your app (host), the agent (model), a check (check), the system, or an AI check (ai). For drafts, the source is who proposed it: model or check.
override and finished are written by the runtime when it records a finish. The browser cannot send them, so a client cannot put a finish into the trail. ai events are written by the runtime too.
How it is sent
- Events are queued and sent in batches about every 2 seconds, and always just before a finish is recorded, so the trail reaches Baseera before the finish does.
- When the page is hidden or closed, a last request goes out with
keepalive. - It is best effort. A failing request is retried twice and then dropped. A trail problem never blocks the person's work or a finish.
- A session is started for the trail only when there is something to send. Opening a record counts.
The timeline in the dashboard
Open the agent, then Immersive mode, then a record under Records. The Record timeline lists everything that happened to that record in order, in UTC. Each event shows its label, who or what caused it, and its details: the check, message, severity, field, reason, the checks overridden, the blocking checks open, the signal, the receipt and the title. AI results carry an "AI check" badge and the sources they used.
Export JSON downloads the record's events. The timeline shows the first 1,000 events and says so when there are more. The export carries up to 5,000. Each event has its id, type, source, user, tenant, the time it occurred (the browser's clock) and the time Baseera recorded it.
The page says what the trail is: "The trail is the browser's account of what happened, recorded as it went. Baseera cannot prove it is true."
The finish webhook
Give the agent a webhook address on its Immersive mode page. When someone finishes a record, Baseera POSTs immersive.record.finished to it. See The dashboard page for setup.
import { verifyWebhook } from "@baseera/node";
export async function POST(request: Request) {
const result = await verifyWebhook(request, process.env.BASEERA_FINISH_WEBHOOK_SECRET!);
if (!result.ok) return new Response(null, { status: 400 });
if (result.event.type === "immersive.record.finished") {
if (await alreadyHandled(result.event.id)) return new Response(null, { status: 200 });
const { entity, receiptId, trail, truncated } = result.event.data;
await saveTrail(entity, receiptId, trail, truncated);
}
return new Response(null, { status: 200 }); // within 5 seconds
}alreadyHandled and saveTrail stand for your own storage. In a Fetch-style handler, pass the Request itself and the body and signature header are read for you. In Node frameworks, pass the raw body: verifyWebhook(rawBody, req.headers["baseera-signature"], secret). See Webhooks for the signature format and Webhook guide for setup.
Payload
{
"id": "evt_01JD...",
"type": "immersive.record.finished",
"createdAt": "2026-11-12T09:41:07.000Z",
"data": {
"agentId": "6f1c...",
"sessionId": "ses_01JC9X4M2K8Q",
"receiptId": "fin_...",
"userId": "user_42",
"tenantId": "t1",
"entity": { "type": "invoice", "ref": "inv_1042" },
"source": "panel",
"startedAt": "2026-11-12T09:38:51.000Z",
"finishedAt": "2026-11-12T09:41:06.000Z",
"openBlocking": ["tax-id-missing"],
"override": { "reason": "Customer confirmed the tax ID by phone", "checks": ["tax-id-missing"] },
"toolDataIncluded": true,
"truncated": false,
"eventCount": 14,
"trail": [
{ "id": 881, "type": "started", "source": "system", "at": "2026-11-12T09:38:51.000Z", "data": { "title": "Invoice 1042" } }
]
}
}Prop
Type
The payload is up to about 250 KB, so your endpoint must accept that.
Delivery
- Answer with any
2xxwithin 5 seconds. - Baseera tries each delivery twice: if the first try fails it tries once more on the next worker pass, about a minute later. Then the dashboard shows it as Failed.
- Every try has the same
Baseera-Event-Id. Keep the ids you handled and ignore a repeat. - The address must be public https. Private, loopback, link-local and metadata addresses are refused when it is saved and again at every send, and redirects are not followed.
- A webhook problem never stops a finish. The finish returns its receipt either way.
The same address also receives eval.run.finished. Ignore event types you do not know.
When tool data is not stored
If the agent is set not to store tool data, draft values, previous values and signal data are removed from the trail before it is stored, and removed again when the webhook is built. toolDataIncluded is false. Names, ids, severities, messages and override reasons are kept: the reason is written by the person for your audit.
The webhook is the browser's account of what happened, not proof. To know a finish really happened, verify its receipt on your server with verifyFinish and match it to receiptId.
Next steps
Finish and overrides
When the Finish button is enabled, the single-use finish receipt, what verifyFinish proves and does not prove, and finishing anyway with a written reason.
Signals
Tell Baseera something happened: a client signal from your UI with useBaseeraSignal, or a server signal from your backend with baseera.signal, and when checks run again.