Available

Webhooks

Delivery attempts, payload variants, receiver safety, and current webhook security behavior.

Updated 2026-07-28

Docparser posts a JSON result to the API key’s registered base URL joined with the relative webhookUrl from the submission. The request uses POST and content-type: application/json.

Delivery contract

A delivery makes up to three attempts. The second attempt begins after 1 second; the third begins after 3 seconds in total. Each attempt has a 15-second timeout. Any 2xx response is successful. A non-2xx response is retried only while configured attempts remain. A failure on the last attempt ends automatic delivery.

After the final attempt, the persisted job exposes the attempt count, latest response status, and latest response body through the retrieve endpoint. For a large receiver response, Docparser stores the first 4,000 characters followed by a truncation marker. When an attempt times out or cannot connect, a response code and body might not exist.

Receiver idempotency

Retries for one job carry the same consumer_ref_id, but consumerRefId is not database-unique and does not make delivery idempotent. The API accepts separate submissions with the same value and retrieval returns the first organization-scoped match.

Use consumer_ref_id as a correlation input in your receiver, then store enough receiver-side state to distinguish a retried delivery from a separate submission—for example, combine it with your own submission record and the payload shape. Return a 2xx status only after the result is safely recorded.

Success payloads

Single document and combined multi-image

Single-document jobs and multi-image jobs using processingMode: "single_invoice" put status and the extracted document fields at the top level. The schema depends on the selected document type.

{
"status": "processed",
"processed_data": {
  "summary_data": {
    "invoice_number": "INV-4471",
    "amount": 1180
  },
  "lineItems": []
},
"consumer_ref_id": "inv-4471",
"document_id": 4471
}

Per-page multi-image

Multi-image jobs using processingMode: "multiple_invoices" return an envelope. Each item under data is a normalized document and carries the same correlation identifiers.

{
"status": "processed",
"consumer_ref_id": "batch-4471",
"document_id": 4471,
"multi_image_mode": "multiple_invoices",
"invoice_count": 2,
"data": [
  {
    "processed_data": {
      "summary_data": { "invoice_number": "INV-1" },
      "lineItems": []
    },
    "consumer_ref_id": "batch-4471",
    "document_id": 4471
  },
  {
    "processed_data": {
      "summary_data": { "invoice_number": "INV-2" },
      "lineItems": []
    },
    "consumer_ref_id": "batch-4471",
    "document_id": 4471
  }
]
}

Email with invoice intent

Email mode first classifies the supplied subject and body. When invoice intent is found, attachments are parsed with the invoice schema and returned as an array.

{
"status": "processed",
"has_invoice": true,
"confidence_score": 0.92,
"processed_data": [
  {
    "summary_data": { "invoice_number": "INV-4471" },
    "lineItems": []
  }
],
"consumer_ref_id": "email-4471",
"document_id": 4471
}

Email without invoice intent

When classification finds no invoice intent, attachment extraction stops. This payload does not currently include consumer_ref_id or document_id; correlate it with receiver-side delivery context rather than expecting those keys.

{
"status": "processed",
"has_invoice": false,
"confidence_score": 0.04,
"processed_data": []
}

Error payload

Extraction failures use the same fixed shape for single, multi-image, and email jobs:

{
"status": "error",
"message": "failed to analyse the document.",
"consumer_ref_id": "inv-4471",
"document_id": 4471
}

An error webhook intentionally uses the public message above; detailed persisted diagnostics are available from the authenticated retrieve endpoint.