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
| Event | Sent when |
|---|---|
knowledge.item.ready | An item pushed through the API (or uploaded by a tenant) becomes searchable. |
knowledge.item.failed | Processing an item failed. |
immersive.record.finished | A finish is recorded for a record in immersive mode. Goes to the agent's own endpoint. |
eval.run.finished | A 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| Header | Meaning |
|---|---|
Baseera-Signature | t=<unix seconds>,v1=<hex> |
Baseera-Event-Id | The same as the body's id, and the same on every retry. |
Baseera-Event-Type | The 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:
- Parse
tandv1from the header. - Compute the HMAC over the exact raw body. Do not parse and re-serialize it first.
- Compare in constant time.
- Refuse a
tmore 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.
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
2xxis 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.