Webhooks
Verify the signature and timestamp of a Baseera webhook with verifyWebhook, and handle each event type.
Baseera sends signed webhooks to your server: when a knowledge item you pushed is ready or failed, when someone finishes a record in immersive mode, and when an eval run ends. verifyWebhook checks the signature and the timestamp and parses the body for you.
Verify a webhook
In a Fetch-style handler, pass the Request itself. The body and the signature header are read for you.
import { verifyWebhook } from "@baseera/node";
export async function POST(request: Request) {
const result = await verifyWebhook(request, process.env.BASEERA_WEBHOOK_SECRET!);
if (!result.ok) return new Response(null, { status: 400 });
const { id, type, data } = result.event;
if (await alreadyHandled(id)) return new Response(null, { status: 200 });
switch (type) {
case "knowledge.item.ready":
case "knowledge.item.failed":
await onKnowledge(type, data);
break;
case "immersive.record.finished":
await saveTrail(data.entity, data.receiptId, data.trail);
break;
case "eval.run.finished":
if (!data.passed) await alertTeam(data.suiteName, data.counts);
break;
}
return new Response(null, { status: 200 });
}This works in Next.js route handlers, Hono, Bun, Deno and Workers: anything with a headers.get and a text().
In Express and other Node frameworks
Pass the raw body and the header. The raw body is the exact bytes, before any JSON parsing.
import express from "express";
import { verifyWebhook } from "@baseera/node";
const app = express();
app.post("/baseera-webhook", express.raw({ type: "application/json" }), async (req, res) => {
const result = await verifyWebhook(req.body, req.headers["baseera-signature"], process.env.BASEERA_WEBHOOK_SECRET!, {
toleranceSec: 300,
});
if (!result.ok) return res.sendStatus(400);
await handle(result.event);
res.sendStatus(200);
});Sign the exact bytes you received. If a JSON middleware parses the body first and you re-serialize it, the signature will not match.
Signature
verifyWebhook(request: WebhookRequestLike, secret: string, options?: VerifyWebhookOptions): Promise<VerifyWebhookResult>;
verifyWebhook(
rawBody: string | Uint8Array,
signatureHeader: string | string[] | null | undefined,
secret: string,
options?: VerifyWebhookOptions,
): Promise<VerifyWebhookResult>;Prop
Type
It never throws. The result is one of:
{ ok: true, event: BaseeraWebhookEvent, timestamp: number }
{ ok: false, reason: "missing_header" | "malformed_header" | "bad_secret" | "timestamp_outside_tolerance" | "signature_mismatch" | "invalid_body" }Answer a failed verification with a 400 and do not process the body. Do not tell the sender which check failed.
What is checked
Every delivery is a POST with a JSON body and three headers:
| Header | Meaning |
|---|---|
Baseera-Signature | t=<unix seconds>,v1=<hex>: the HMAC-SHA256 of t, a dot and the raw body, with your endpoint's signing secret. |
Baseera-Event-Id | evt_ and an id. The same on every retry. |
Baseera-Event-Type | The event type. |
verifyWebhook recomputes the HMAC and compares it in constant time. It refuses a timestamp more than toleranceSec from now, so a captured request cannot be replayed later. If the header holds several v1 values (a secret being rotated), it passes when any one matches. A repeated header, which Node gives as an array of several values, is refused as ambiguous.
The signing secret starts with whsec_. It is shown once in the console when you set the endpoint. Keep it in your secret manager, never in the repository.
Events
| Type | Sent when | data |
|---|---|---|
knowledge.item.ready | A pushed item is searchable. | knowledgeBaseId, sourceId, externalId, tenantId, version, status, errorCode, chunkCount. |
knowledge.item.failed | A pushed item failed to process. | The same, with status: "failed" and an errorCode such as parse_failed or no_text. |
immersive.record.finished | Someone finishes a record in immersive mode. | entity, receiptId, userId, tenantId, openBlocking, override, trail, truncated, and more. |
eval.run.finished | An eval run started by your CI or by a changed tool manifest ends. | runId, suiteName, target, status, passed, counts. |
Knowledge events never hold document content: only ids, a status and an error code. The constants FINISH_WEBHOOK_EVENT_TYPE and WEBHOOK_TOLERANCE_SECONDS are exported, and so is the BaseeraWebhookEvent type, a union of the event shapes.
Ignore event types you do not know. New ones can be added.
Handle retries
Deliveries are retried, so the same event can arrive twice. Keep the id of every event you handled, and ignore a repeat (result.event.id, also in the Baseera-Event-Id header). Answer with any 2xx quickly. A knowledge endpoint retries other answers six times over about an hour. An agent's webhook (finish and eval events) expects an answer within 5 seconds and retries a failure once.
The finish webhook
An owner or admin sets the agent's webhook address on its Immersive page. The address must be a public https address. Private, loopback, link-local and metadata addresses are refused when it is saved and again at every send, and redirects are not followed. The payload is up to about 250 KB.
if (result.event.type === "immersive.record.finished") {
const { entity, receiptId, trail, truncated } = result.event.data; // truncated: the oldest events were left out
await saveTrail(entity, receiptId, trail);
}The payload is the user's browser's account of what happened, not proof. For a guarantee, confirm the receipt (receiptId) with verifyFinish.
The eval webhook
if (result.event.type === "eval.run.finished") {
const { runId, suiteName, passed, counts, target } = result.event.data;
if (!passed) await alertTeam(`${suiteName} failed on ${target}: ${counts.failed} failed, ${counts.errored} errored (run ${runId})`);
}It carries pass or fail and counts only: no case names, messages or text.
Test your handler
generateWebhookSecret() returns a new signing secret (whsec_ and 43 URL-safe characters). Use it to sign test deliveries, and pass now to verifyWebhook to test the timestamp window.