Webhooks

Webhooks overview and events

Tell your own tools the moment a document base is ready, a sync run finishes or a document fails, instead of polling for it. Signed, retried, and recorded in your audit log.

A pipeline that loads documents and then waits has two options, and polling is the worse one: it burns your CI minutes and our request budget to learn something we knew the instant it happened. Webhooks are the other option.

What you get

You give us an HTTPS endpoint. When a run finishes, a base starts answering, or a document cannot be read, we POST a signed JSON body to it, retry it if your endpoint is down, and record every attempt in your audit log. Three properties hold the design together:

Your pipeline is never the reason ingestion fails. Emitting an event writes nothing to the network: it queues, and delivery happens on a worker. An unreachable endpoint of yours can never turn a finished onboarding into a failed one.
You can prove a call came from us. Every delivery carries an HMAC-SHA256 signature over the exact bytes we sent. See Verify a signature.
A failed delivery is retried, and then it stops. One attempt and five retries, six deliveries over about an hour and three quarters, which covers a deploy or a restart. See Delivery and retries.
You can replace a secret or pause an endpoint without rebuilding it. The id stays the same, so nothing you keyed on it has to change. See Replace a signing secret and Pause and resume.

The events

Three events, a closed set. An unknown name in a subscription is refused at the call that made it rather than surfacing months later as "why does my endpoint never fire".

Event	Fires when	Key fields
`sync_run.completed`	An ingestion run reaches a terminal state, whatever fed it: an upload, a push, an S3 sync, a Drive or SharePoint sync	`sync_run_id`, `corpus_id`, `source`, `state`, `counters`
`corpus.ready`	A document base finishes onboarding and is answering queries	`corpus_id`, `name`, `job_id`, `documents_ready`
`document.failed`	One document could not be read or built, with the reason	`corpus_id`, `document_id`, `path`, `lifecycle`, `error`

Subscribe with an empty events list to get all three, which is what someone who just wants to be told things should do rather than maintaining an enumeration.

What a payload looks like

Every delivery has the same envelope: the event name, when we sent it, and the event's own data.

{
  "event": "sync_run.completed",
  "sent_at": "2026-09-13T10:06:39.411820Z",
  "data": {
    "sync_run_id": "r_5d2c...",
    "corpus_id": "c_7a1f...",
    "source": "s3",
    "source_id": "s_3e8b...",
    "state": "succeeded",
    "counters": {"added": 12, "updated": 3, "unchanged": 480, "removed": 0, "failed": 1},
    "documents_total": 15,
    "documents_done": 15,
    "error": null
  }
}

{
  "event": "corpus.ready",
  "sent_at": "2026-09-13T10:11:42.004913Z",
  "data": {
    "corpus_id": "c_7a1f...",
    "name": "Support handbook",
    "job_id": "j_4b8e...",
    "documents_ready": 495
  }
}

{
  "event": "document.failed",
  "sent_at": "2026-09-13T10:09:02.771004Z",
  "data": {
    "corpus_id": "c_7a1f...",
    "document_id": "d_92f...",
    "path": "handbook/scanned-appendix.pdf",
    "lifecycle": "failed",
    "error": "encrypted PDF: no readable text"
  }
}

source says which route the documents came in by: upload (a manifest commit, which is what the Documents tab and engram push both do), push (the API's single-document documents/upsert), s3, google_drive, sharepoint or backfill. The first two are worth reading twice, because the names are not the ones you would guess; the full table is on Keeping a source in sync.

Every timestamp we send is UTC and ends in Z, in a payload's sent_at and in the created_at and last_delivery_at on the listing alike.

A run is succeeded even when a counter says one document failed: a run fails only when nothing it tried worked. So watch counters.failed and the document.failed events for per-file problems, and state for whether the run itself got anywhere.

The headers on a delivery

Header	Value
`X-Engram-Signature`	`sha256=<hex>`, an HMAC-SHA256 of the raw body bytes with your endpoint's secret
`X-Engram-Event`	The event name, so you can route before parsing
`Content-Type`	`application/json`
`User-Agent`	`engram-webhooks/1`

Verify the signature before you trust X-Engram-Event or anything in the body. The header is convenience; the signature is the proof.

Which plan turns this on

Subscribing a new endpoint comes with the Pro plan and every tier above it. Exactly what each tier includes is on Plans and allowances, which is the single place those numbers live.

Only subscribing is gated. Listing, removing, pausing and rotating a secret stay open on every tier, and deliveries to endpoints that already exist keep running whatever plan the workspace moves to, because a pipeline going quiet without warning is a worse failure than an unenforced promise.

Set one up in one call: Subscribe an endpoint. Then verify a signature and read delivery and retries before you put a receiver in production.