Skip to main content

Knowledge Webhooks

Knowledge bases send their events through the platform Webhooks. Add an endpoint once (portal: Settings → Integrations → Webhooks, or POST /v1/webhooks) and subscribe to the knowledge.* events below. Setting up an endpoint, verifying signatures, retries, test events, redelivery and the endpoint rules are all on that page.

Moved to the platform webhooks

Knowledge webhooks used to be managed at /v1/knowledge_webhooks, with event names without the knowledge. prefix (document.ready) and a different envelope (contract_version, occurred_at inside data). That route is removed: /v1/knowledge_webhooks (and the old /v1/knowledge_connections) answer 404 not_found, and endpoints registered there are not carried over. Knowledge events go only to platform webhooks, in the format described here.

Events​

EventSent whendata
knowledge.document.readyA document version becomes the searchable version: a first upload, a replacement, or a page of a website sourcedocument fields
knowledge.document.failedA version fails, including after 24 h in awaiting_budget (awaiting_budget_timeout). For a failed replacement the previous version stays readydocument fields, with failure set
knowledge.document.deletedA document deletion is accepted (access is already closed). Also sent for every document of a deleted knowledge basedocument fields
knowledge.export.readyAn export zip is ready to downloadexport fields
knowledge.source.sync_completedA website source's sync run ended, whatever the result (completed, held, stopped, failed, cancelled). Exactly one per runsource fields, with run
knowledge.source.blockedA website source became blocked_by_site (the site refused) or disabled_by_admin (the platform blocked the domain or switched website sources off for your organization)source fields; run is the run that found it, or null

Events are recorded in the same transaction as the change, so you never get an event for a change that did not happen, or miss one for a change that did. A slow or failing endpoint never delays document processing.

Event typedata fields
knowledge.document.*knowledge_base_id, document_id, origin (upload or web), source_id (the website source of a page, otherwise null), status (after the event), name, size_bytes, sha256, failure ({code, message, retryable} or null)
knowledge.export.readyknowledge_base_id, export_id, document_count, size_bytes, expires_at
knowledge.source.*knowledge_base_id, source_id, source_type (website; treat other values as opaque), host (the start URL's host, never the full URL), status and status_reason (the source's, after the event), run; connection_id is absent or null for website sources

The envelope around data (id, type, version, occurred_at, …) is described in Payload. Use occurred_at to order events for the same document: delivery order is not guaranteed.

  • knowledge.export.ready deliberately carries no download link, so signed links never end up in your receiver's logs. Fetch it with GET /v1/knowledge_bases/{kb_id}/exports/{export_id}.
  • Payloads never contain document text, extracted content or metadata values.

Website source events​

Pages of a website source are ordinary documents: they send knowledge.document.ready, knowledge.document.failed and knowledge.document.deleted like uploads, with origin: "web" and the source_id, so you can filter them. An unchanged page sends nothing. Two events describe the source itself:

  • knowledge.source.sync_completed is sent once for every run, whatever its end. A held run, a failed run and a blocked run are not separate event types: read data.run.status and data.run.stop_reason (the values are listed in Sync runs). Resolving a held run sends no second knowledge.source.sync_completed; the pages it deletes send knowledge.document.deleted.
  • knowledge.source.blocked is sent when a source becomes blocked_by_site or disabled_by_admin. A run that is stopped by the site sends both events. A block that happens without a run (for example when the platform blocks a domain after a removal request) sends only knowledge.source.blocked, with run: null.

data.run is {id, trigger, status, stop_reason, started_at, finished_at, counts} (trigger is manual or scheduled). counts has discovered, fetched, not_modified, unchanged, new, changed, removed, pending_removal, failed and skipped. Call GET …/sources/{source_id}/runs/{run_id} for the full run.

{
"id": "0c1d2e3f-4a5b-5c6d-8e7f-9a0b1c2d3e4f",
"type": "knowledge.source.sync_completed",
"version": 1,
"scope": "tenant",
"tenant_id": "9d2e4b1a-7c3f-4e5d-8a6b-1c2d3e4f5a6b",
"occurred_at": "2026-09-27T10:39:58.101010Z",
"created_at": "2026-09-27T10:40:00.123456Z",
"data": {
"knowledge_base_id": "3f6c2b1e-8d4a-4c1f-9e2b-7a5d6c3b2a10",
"source_id": "5a4b3c2d-1e0f-4a9b-8c7d-6e5f4a3b2c1d",
"source_type": "website",
"host": "docs.example.com",
"status": "held",
"status_reason": "deletion_threshold",
"run": {
"id": "7e3f1c2a-9b8d-4e6f-8a1b-2c3d4e5f6a7b",
"trigger": "manual",
"status": "held",
"stop_reason": "deletion_threshold",
"started_at": "2026-09-27T10:00:00Z",
"finished_at": "2026-09-27T10:39:58Z",
"counts": { "discovered": 80, "fetched": 60, "not_modified": 0, "unchanged": 55,
"new": 3, "changed": 2, "removed": 0, "pending_removal": 27,
"failed": 0, "skipped": 20 }
}
}
}

Source payloads never contain page text or full URLs, only the host. Losing a domain verification sends no webhook (the organization owner gets an email).

Recovering missed events​

A delivery that failed for 24 hours is dropped. Send it again from the endpoint's delivery list (Deliveries), or catch up from the API: list documents with ?updated_since=, and for website sources list the sources and their runs (GET …/sources, GET …/sources/{source_id}/runs).