Webhooks

Register a URL to be called when a batch finishes processing, or list the persisted event feed for polling integrations such as Zapier triggers. For callback payload shape, the three signature headers, and the retry schedule, see the Webhooks guide — including how reprocessing a batch (uploading and processing more documents into a batch_name that already notified you once) gets its own, separate notification automatically, with no action needed on this endpoint.

There is no separate registration for bbox completion. The same callback_url you register here also receives a document.bbox_completed event whenever a bbox annotation job finishes on any document in this batch — triggering bbox does not require (or support) its own webhook endpoint. See the Webhooks guide for the event payload shape and the delivery caveat specific to bbox.

Register a batch webhook

Creates or updates the completion callback for one batch. You can also set webhook_url directly on Start processing a batch to register it in the same call — this endpoint exists for registering (or changing) it separately, e.g. before you're ready to call process, or to fix a typo'd URL afterward.

Parameters

webhook_secret is returned in every successful response — on first registration and on every subsequent update — not masked after the first call. There is no separate GET for this resource, so re-PUT-ing the same callback_url is the supported way to retrieve your secret again if you lose it. Updating an existing registration only ever touches callback_url: webhook_secret is never rotated by this call, and fired_at (whether this batch's most recent wave of processing has already notified you) is never reset by this call. Re-arming fired_at for a new wave happens on Start processing a batch instead, automatically, the moment it finds new eligible documents in a batch whose previous wave already fired — see the Webhooks guide's "Reprocessing a batch" section. Re-PUT-ing this endpoint does not by itself get you notified again.

Delivered event payloads

Once registered, callback_url receives a POST for either of two event types, distinguished by the top-level "type" field — this endpoint itself never returns either shape; these are what your server receives.

batch.completed — fires once, when every document in the batch reaches a terminal status:

{
  "type": "batch.completed",
  "created_at": "2026-07-16T09:14:31Z",
  "data": {
    "batch_name": "260716-4K9P",
    "status": "succeeded",
    "document_count": 3
  }
}

document.bbox_completed — fires when a bbox annotation job triggered on any document in this batch finishes:

{
  "type": "document.bbox_completed",
  "created_at": "2026-07-16T09:20:07Z",
  "data": {
    "document_id": "3f9c9e2a-1b7d-4e2b-9a3e-2f5b6c7d8e9f",
    "group_batch_id": "bx_8a3c2e1f",
    "status": "succeeded"
  }
}

Neither payload carries the extracted results themselves — call GET /batches/{batch_name}/results or GET /documents/{document_id}/bbox after receiving the corresponding event to fetch the actual data. Both events are delivered at most once per completion, even when several documents (or several bbox row-groups) reach a terminal status within moments of each other — see the Webhooks guide for the signature headers and retry schedule.

List events

Returns a persisted, newest-first event feed for polling integrations. This is the right endpoint for Zapier polling triggers such as "New Completed Batch", "New Completed Document", and "Failed Extraction" — it does not require users to hand-enter a batch_name into the trigger.

Parameters

Events are created only after the worker has committed the terminal document state, so by the time an event appears here, its document_url, batch_url, and batch_results_url targets are safe to read. Use id as the deduplication key. If a failed document is reprocessed and reaches a terminal state again, or a completed batch later gets another processed wave, the new completion gets a new event id.

Possible errors

• missing_api_key / invalid_api_key / plan_required — see Error Handling.
• invalid_parameter — bad type, limit, page_token, batch_name, created_from, or created_to.

Possible errors

• missing_api_key / invalid_api_key / plan_required — see Error Handling.
• missing_parameter (param: "callback_url")
• invalid_parameter (param: "callback_url") — not an http:///https:// URL.
• invalid_parameter (param: "batch_name")