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:

• app.run.completed — An App run reached a sealed decision record.
• app.run.failed — An App run failed before reaching a decision.
• app.exception.raised — An App raised a system exception (threshold breach or validation failure) into the review queue.
• app.review.raised — A Human Review was raised on an App run.
• app.review.resolved — A Human Review was resolved; the resolution and feedback are available.
• app.action.execute — An App decision executes an action; the payload carries the decision, evidence, and idempotency key.
• app.version.activated — An App published and activated a new version.
• 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.
• run.cancelled — A Spec pipeline was stopped through POST /v1/run/:id/cancel or POST /v1/pipelines/:id/cancel. Every live /v1/run request on the pipeline receives its own event (run_id set); the pipeline-level copy has none. The payload carries reason and cancelled_at, never output rows; results completed before the cancel stay readable.

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.

The app.* family covers Apps — versioned decision units that read a governed data product and emit verdicts. Subscribe to app.run.completed to consume sealed decision records, app.review.raised and app.review.resolved to mirror the Human Review inbox into your own tooling, and app.action.execute to trigger side effects: its payload carries the decision, the supporting evidence, and an idempotency key so your action handler can deduplicate re-deliveries.

When an event fires, Talonic fans out one delivery per matching webhook target — every active configuration subscribed to the event, plus any per-request webhook_url override — and reports the number of targets it enqueued. Zero enqueued targets means no subscriber matched the event (or every target was rejected by the SSRF guard), so nothing will be delivered for that occurrence.

{
  "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 }
    ]
  }
}