Skip to Content
Baseera Docs

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

TypeTimeline labelWhenData
startedImmersive mode startedThe record opened.title?
check_raisedCheck raisedA check started failing.id, severity, message, fields
check_resolvedCheck resolvedA check started passing.id, severity, message, fields
draft_proposedDraft proposedA draft appeared in a field.field, reason, value
draft_approvedDraft approvedThe person approved a draft.field, reason, value, previous
draft_rejectedDraft rejectedThe person rejected it, or it was replaced or the record closed.field, reason
acknowledgedAcknowledgedThe person dismissed a warning or info.id, severity, message, fields
signalSignal from the appYour UI sent a signal.name, signalData?
overrideOverride with a reasonThe person finished with blocking checks open.reason, checks
finishedFinishedThe 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.

app/api/baseera/finish-webhook/route.ts
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

immersive.record.finished
{
  "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 2xx within 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

On this page