Skip to Content
Baseera Docs

Webhooks

The events Baseera sends to your server, their payloads, the signature header, retries and a verification example.

Baseera POSTs signed events to an https address you set in the console. Use them to learn when a document is indexed, when a record is finished, and when a test run ends.

Set up

An owner or admin sets the endpoint in the console: an https address, the events, and a signing secret (whsec_...). The secret is shown once, and saving again makes a new one. The console lists recent deliveries with their status.

The address goes through the same fetcher as a url knowledge item. Only https and public addresses are allowed, and the address is checked at every delivery. A redirect is a failure and is never followed.

Events

EventSent when
knowledge.item.readyAn item pushed through the API (or uploaded by a tenant) becomes searchable.
knowledge.item.failedProcessing an item failed.
immersive.record.finishedA finish is recorded for a record in immersive mode. Goes to the agent's own endpoint.
eval.run.finishedA run started by the eval API or the manifest trigger ends. Goes to the agent's own endpoint.

Request

POST /your/webhook
Content-Type: application/json
Baseera-Signature: t=1794391200,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd
Baseera-Event-Id: evt_3f1c...
Baseera-Event-Type: knowledge.item.ready
HeaderMeaning
Baseera-Signaturet=<unix seconds>,v1=<hex>
Baseera-Event-IdThe same as the body's id, and the same on every retry.
Baseera-Event-TypeThe event type.

Every body has the same envelope:

{ "id": "evt_3f1c...", "type": "knowledge.item.ready", "createdAt": "2026-11-11T10:00:00Z", "data": {} }

Payloads

knowledge.item.ready

{
  "id": "evt_3f1c...",
  "type": "knowledge.item.ready",
  "createdAt": "2026-11-11T10:00:00Z",
  "data": { "knowledgeBaseId": "...", "sourceId": "...", "externalId": "refund-policy", "tenantId": null, "version": 2, "status": "ready", "errorCode": null, "chunkCount": 4 }
}

knowledge.item.failed

Same shape with status: "failed" and an errorCode: parse_failed, no_text, too_large, unsupported_type, fetch_failed, blocked_url, invalid_key, no_credit, rate_limited, provider_error or timeout. The body never holds document text, titles or metadata.

immersive.record.finished

data carries agentId, sessionId, receiptId, userId, tenantId, entity, source, finishedAt, startedAt, openBlocking, override, toolDataIncluded, truncated, eventCount and trail. The trail is redacted again at send time when the agent does not store tool data, and capped at about 250 KB. truncated says when the oldest events were cut.

eval.run.finished

{
  "id": "evt_...",
  "type": "eval.run.finished",
  "createdAt": "2026-11-13T10:00:30Z",
  "data": {
    "agentId": "...", "runId": "...", "suiteId": "...", "suiteName": "core", "source": "manifest", "target": "v7",
    "status": "done", "passed": false, "minPassRate": 100,
    "counts": { "total": 24, "completed": 24, "passed": 22, "failed": 2, "errored": 0 },
    "finishedAt": "2026-11-13T10:00:30.412Z"
  }
}

Pass or fail and counts only. Runs started from the console do not send it.

Verify the signature

v1 is the lowercase hex HMAC-SHA256 of `${t}.${rawBody}` with the signing secret, where t is unix seconds. To verify:

  1. Parse t and v1 from the header.
  2. Compute the HMAC over the exact raw body. Do not parse and re-serialize it first.
  3. Compare in constant time.
  4. Refuse a t more than 5 minutes from your clock. That is replay protection.

A header may carry several v1 values while a secret is being rotated. Accept the request when any one matches.

app/api/baseera-webhook/route.ts
import { verifyWebhook } from "@baseera/node";

export async function POST(request: Request) {
  const result = await verifyWebhook(request, process.env.BASEERA_WEBHOOK_SECRET!, { toleranceSec: 300 });
  if (!result.ok) return new Response(null, { status: 400 });

  if (await alreadyHandled(result.event.id)) return new Response(null, { status: 200 });

  if (result.event.type === "knowledge.item.ready") {
    await markIndexed(result.event.data.externalId);
  }
  return new Response(null, { status: 200 });
}

verifyWebhook takes a Fetch Request, or the raw body, the Baseera-Signature header and the secret. It never throws. Its failure reasons include invalid_body.

Delivery and retries

  • Any 2xx is success. Anything else, a timeout or a connection failure is a failure.
  • Knowledge events: 10-second timeout, retried after 30 seconds, 2, 5, 15 and 30 minutes (six tries in about an hour), then dropped.
  • The finish event: 5-second timeout and one retry.
  • The eval event: two tries.
  • A fresh timestamp is signed for every try.
  • Deliveries are sent by a worker that runs at most once a minute, so an event can arrive a minute late.

Because of retries, handle each event id once. Baseera-Event-Id is stable across retries, so store the ids you have processed and ignore repeats.

A failing webhook never blocks or fails the action that caused it. Failures show in the console with Baseera's own short error code, never your server's response text.

Next steps

On this page