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 — they are not the log, and 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" } }

Note what the payload is not: content never appears. 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 — the MCP write path 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 — the write 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, because an operator whose outbox never drains has no other way to notice.

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 and each pass stays cheap.