Events

Subscribe to webhook events across the document lifecycle: extraction.complete, extraction.failed, job.complete, delivery.sent, run.completed, and more.

Webhook events are real-time HTTP POST notifications that Talonic sends to your server when something happens to a document, extraction, job, or run. Instead of polling the API, you register a URL and receive a JSON payload within seconds of each event. Configure webhook URLs per-source or workspace-wide via [webhook configurations](create-webhook-config), or per-extraction via the webhook_url option on POST /v1/extract.

Available webhook events:

• document.uploaded — A new document has been uploaded and queued for processing.
• document.processing — Document OCR and classification has started.
• document.classified — Document type and language have been detected.
• extraction.started — AI data extraction has begun on the document.
• extraction.complete — Data extraction finished successfully. Extracted fields are available.
• extraction.failed — Data extraction failed after all retry attempts.
• job.created — A new Job (formerly called a structuring run) has been created.
• job.started — Job processing has begun.
• job.phase_complete — A job phase (resolve, extract, normalize, or transform) has completed.
• job.complete — All job phases finished. Structured results are available.
• job.failed — Job processing failed.
• review.approved — A record has been approved in Record Review.
• delivery.sent — An outbound delivery was sent successfully.
• delivery.failed — An outbound delivery failed after all retry attempts.
• process.completed — A document processing run finished all steps and the result is available.
• process.failed — A document processing run failed. The error payload includes the step name and error detail.
• run.completed — A POST /v1/run Spec pipeline finished; structured output is available (review-held fields null). The payload carries records[] — always an array, one {document_id, filename, data, metadata?, batch_id?} entry per output row (metadata/batch_id are the submitting request's per-input tags, present only when set) — alongside the legacy structured_data field kept for compatibility; prefer records.
• run.failed — A POST /v1/run Spec pipeline failed because every document errored during ingest or extraction. When the failure occurred at the ingest leg, the error payload includes document_ids, the best-effort list of documents that were being ingested.

Most integrations subscribe to extraction.complete to trigger downstream processing, for example writing structured data to a database or notifying a user. A typical workflow is to pass webhook_url on POST /v1/extract, then handle the callback payload in your server without polling. New webhook configurations subscribe to extraction.complete and extraction.failed by default.

The data object of each payload is event-specific. For extraction.complete it includes the document_id, extraction_id, filename, field_count, and confidence_overall score. Use the extraction_id to fetch the full result via GET /v1/extractions/:id when the payload does not contain all the fields you need.

Pair event handling with [Signature Verification](webhook-security) to ensure payloads are authentic. extraction.failed and process.failed events include an error field with a machine-readable code and human-readable message: use it to decide whether to retry via POST /v1/extract with document_id.

{
  "event": "run.completed",
  "delivery_id": "dlv_a1b2c3d4e5f67890",
  "timestamp": "2026-07-14T21:06:48.977Z",
  "data": {
    "pipeline_id": "1a0c681d-ea20-4bb4-8892-01a6d7f834da",
    "schema_id": "1fc7807e-e1aa-4504-b796-5709986e78ed",
    "status": "completed",
    "records": [
      {
        "document_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
        "filename": "invoice-0847.pdf",
        "data": { "vendor_name": "Acme Corp", "total_amount": 14250.00 },
        "metadata": { "source_system": "sap", "priority": 1, "cost_center": "AP-14" },
        "batch_id": "ERP-2026-07-14-001"
      }
    ],
    "structured_data": [
      { "vendor_name": "Acme Corp", "total_amount": 14250.00 }
    ]
  }
}