Webhooks & events

The event log comes first

eventStatement returns a statement rather than executing one, so the caller folds it into the same atomic batch as the write it describes. An event can never exist for a write that rolled back, and can never be missing for one that committed. Webhooks are a delivery mechanism layered on that log: losing a delivery never loses an event.

GET /v1/events is cursor polling: after (an event id), limit (1 to 200, default 50), kind. GET /v1/events/:id fetches one.

{ "data": { "events": [
    { "id": "evt_c7a15e9b3790444dad5fcba5668a73da",
      "kind": "observation.appended",
      "actor_id": "agent_8df7b8699a0945488ceb3d4b104006d6",
      "resource_type": "observation",
      "resource_id": "obs_ed91a2d0f66143fbba66c932494d5e64",
      "payload": { "subject_id": "user_rama", "kind": "tool_result",
                   "trust": "verified", "visibility": "team" },
      "created_at": "2026-07-30T10:38:43.062Z" } ],
    "cursor": "evt_4ff141c765f045d6824c7e2b66732eb5" },
  "meta": { "request_id": "req_da2420eee58d4a88b146e1cf297fc5d9" } }

Content never appears in the payload. You get scope and classification, plus resource_id to fetch the record through an authorized route.

Eleven kinds, and that is the whole list: key, webhook, workspace, membership, policy and federation administration emits nothing. Neither does titen_remember, which skips the event statement, so an observation appended through a tool triggers no webhook.

Registering a webhook

curl -X POST http://127.0.0.1:8787/v1/webhooks \
  -H "authorization: Bearer $TITEN_API_KEY" -H 'content-type: application/json' \
  -d '{"url":"https://hooks.example.internal/titen",
       "secret":"a-secret-at-least-16-chars",
       "events":["claim.materialized","handoff.created"]}'

{ "data": { "webhook_id": "whk_07218864d17b4f44a2367b8e717ff3bb",
    "url": "https://hooks.example.internal/titen",
    "events": ["claim.materialized", "handoff.created"],
    "status": "active", "created_at": "2026-07-30T10:47:59.369Z",
    "signing": { "header": "X-Titen-Signature", "algorithm": "HMAC-SHA256",
      "format": "sha256=<hex>",
      "note": "Compute HMAC-SHA256 of the raw JSON body using your secret to verify deliveries." } },
  "meta": { "request_id": "req_d67ca979b1b24c47b319d5689cc6fa58" } }

Verifying a delivery

const enc = new TextEncoder();

export async function verify(secret: string, rawBody: string, header: string | null) {
  if (!header?.startsWith('sha256=')) return false;
  const hex = header.slice(7);
  if (hex.length !== 64) return false;
  const key = await crypto.subtle.importKey(
    'raw', enc.encode(secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['verify'],
  );
  const sig = Uint8Array.from(hex.match(/../g)!.map((b) => parseInt(b, 16)));
  return crypto.subtle.verify('HMAC', key, sig, enc.encode(rawBody));
}

Sign the bytes you received, not a re-serialized object: a JSON round trip reorders keys and the signature stops matching.

Pause, resume, inspect

Ten consecutive failures move a hook to disabled, and that state is terminal: pause answers Cannot pause a disabled webhook. and resume answers Cannot resume a disabled webhook. Re-register it. Both are 403.

{ "data": { "deliveries": [
  { "id": "dlv_6cabce9807f741b58609e6a5dc3b809e",
    "event_id": "evt_7890988d21c6467095bf714f9dc845fc",
    "status": "pending", "attempts": 1,
    "last_attempt_at": "2026-07-30T10:48:05.752Z",
    "next_retry_at": "2026-07-30T10:49:05.752Z",
    "response_status": null,
    "created_at": "2026-07-30T10:48:05.752Z" } ] } }

Delivery rows are metadata too: a status, an attempt count and the response code, never a response body.

Who drives delivery

An outbound request cannot happen inside a canonical write, which must not wait on someone else’s server, so delivery is pulled from the log afterwards. Who does the pulling depends on the runtime, and /readyz reports it under capabilities.background_repair, which is the only warning an operator gets that the outbox is not draining.

On Bun the timer arms only when the maintenance interval is above zero and either a vector capability is configured or you passed an interval explicitly. A plain titen serve with no embedding endpoint therefore reports background_repair: "disabled". If you registered a webhook on that deployment, nothing will deliver it until you call the drain.

curl -X POST "http://127.0.0.1:8787/v1/webhooks/deliver?limit=50" \
  -H "authorization: Bearer $TITEN_API_KEY"

{ "data": { "events_drained": 5,
    "cursor": "evt_7890988d21c6467095bf714f9dc845fc",
    "pending_deliveries": 2 },
  "meta": { "request_id": "req_7ff7533b486a4d68a8b7fec51566c79c" } }

after and limit (1 to 200, default 50) bound the pass. Without after it scans from the start of the organization’s event log every time and leans on the dedup guard to avoid resending, so feed the returned cursor back on the next call to keep each pass cheap.