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.
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
| Event | Sent when | data |
|---|---|---|
knowledge.document.ready | A document version becomes the searchable version: a first upload, a replacement, or a page of a website source | document fields |
knowledge.document.failed | A version fails, including after 24 h in awaiting_budget (awaiting_budget_timeout). For a failed replacement the previous version stays ready | document fields, with failure set |
knowledge.document.deleted | A document deletion is accepted (access is already closed). Also sent for every document of a deleted knowledge base | document fields |
knowledge.export.ready | An export zip is ready to download | export fields |
knowledge.source.sync_completed | A website source's sync run ended, whatever the result (completed, held, stopped, failed, cancelled). Exactly one per run | source fields, with run |
knowledge.source.blocked | A 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 type | data 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.ready | knowledge_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.readydeliberately carries no download link, so signed links never end up in your receiver's logs. Fetch it withGET /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_completedis sent once for every run, whatever its end. A held run, a failed run and a blocked run are not separate event types: readdata.run.statusanddata.run.stop_reason(the values are listed in Sync runs). Resolving a held run sends no secondknowledge.source.sync_completed; the pages it deletes sendknowledge.document.deleted.knowledge.source.blockedis sent when a source becomesblocked_by_siteordisabled_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 onlyknowledge.source.blocked, withrun: 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).