📺 Webhook Event Types

The full list of events we deliver to your configured webhook endpoint. Subscribe by simply registering an endpoint — you'll receive every event type by default. (Filtering subscriptions is on the roadmap.)

Data extraction events

`extraction.completed`

Fires when a batch finishes processing — all files have a terminal status (processed, needs_review, or failed).

json

{
  "type": "extraction.completed",
  "data": {
    "extraction_id": "ext_01HQX...",
    "batch_id":      "btc_01HQX...",
    "status": "processed",
    "file_count": 3,
    "page_count": 14
  }
}

`extraction.failed`

A batch failed before any file could be processed (e.g. all files rejected as unsupported type).

`file.processed`

A single file finished successfully. Useful when you want to start downstream work file-by-file rather than waiting for the whole batch.

json

{
  "type": "file.processed",
  "data": {
    "extraction_id": "ext_01HQX...",
    "batch_id":      "btc_01HQX...",
    "file": {
      "id": "file_01HQX...",
      "file_name": "INV-1024.pdf",
      "page_count": 3,
      "status": "processed"
    }
  }
}

`file.failed`

A single file failed permanently (after our internal retries).

`file.needs_review`

A file completed but at least one field has confidence below the threshold. The result is available but you'll typically want a human to review.

Document classification events

`classification.completed`

A classification batch finished.

`file.classified`

A single file received a category assignment.

json

{
  "type": "file.classified",
  "data": {
    "classification_id": "cls_01HQX...",
    "file": {
      "id": "file_01HQX...",
      "category_id": "cat_invoice",
      "category_name": "Invoice",
      "confidence": 0.98
    }
  }
}

Test events

`endpoint.test`

Fired only when you click Send test event in the dashboard. Safe to ignore in production — payload contains a friendly hello message so you can verify signature verification end-to-end.

json

{
  "type": "endpoint.test",
  "data": {
    "message": "This is a test event from DocParse. If you see this in your server logs, your webhook endpoint is configured correctly."
  }
}

Lifecycle events (coming soon)

api_key.created / api_key.revoked
usage.threshold (alerts when monthly page usage crosses 50%, 80%, 100%)

Let us know which lifecycle events would unblock a specific workflow and we'll prioritize them.