> This page is for version v1 (default). > For other versions, use one of these documentation indexes: > - v1 (default): https://docs.plextera.com/v-1/llms.txt > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.plextera.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.plextera.com/_mcp/server. # Event Reference The Event Reference documents webhook payloads delivered by Plextera to endpoints configured through [Event Subscriptions](/guides/core-guides/event-subscriptions). --- ## How events are delivered Plextera sends an HTTP POST to your `endpointUrl` with a JSON body and standard headers. Every delivery is signed with the server-generated `signingSecret` returned when you create the subscription. See [Verifying signatures](/guides/core-guides/event-subscriptions#verifying-signatures). Plextera records one immutable event per source event and creates one automatic delivery for each matching active subscription. If a document extraction is reprocessed after a terminal state, a later terminal state can produce a new event. --- ## Common envelope All events share the same top-level structure: ```json { "eventId": "evt_01JY7M9QWBWCPMZK5QJ7RSE9P4", "eventType": "document-insights.extraction.completed", "occurredAt": "2026-04-07T10:22:00Z", "apiVersion": "v1", "data": { "...": "event-specific payload" } } ``` | Field | Description | | ------------ | ------------------------------------------------------------------------- | | `eventId` | Unique event identifier. Stable across retry attempts for the same event. | | `eventType` | Event type string. | | `occurredAt` | UTC ISO 8601 timestamp when the terminal state was reached. | | `apiVersion` | API version used to format the payload, for example `v1`. | | `data` | Event-specific payload. | --- ## Document Insights events Document Insights events use the same extraction structure returned by `GET /document-insights/extractions/{extractionId}`. Completed events include `output`; failed and rejected events include `error`. ### `document-insights.extraction.completed` Delivered when a Document Insights extraction reaches `COMPLETED`. ```json { "eventId": "evt_01JY7M9QWBWCPMZK5QJ7RSE9P4", "eventType": "document-insights.extraction.completed", "occurredAt": "2026-04-07T10:22:00Z", "apiVersion": "v1", "data": { "extractionId": "69654f0bc073ef404baec649", "status": "COMPLETED", "outputAvailable": true, "createdAt": "2026-04-07T10:05:04Z", "updatedAt": "2026-04-07T10:22:00Z", "completedAt": "2026-04-07T10:22:00Z", "labels": { "customerDocumentId": "doc-42", "docType": "invoice" }, "document": { "fileId": "file_01JY7M4ZVX5R1P3M3Q0TA1S7ZM", "fileName": "invoice.pdf", "mimeType": "application/pdf", "size": 63877, "pageCount": 1 }, "output": { "fieldCount": 3, "fields": [ { "id": "field_01", "name": "vendorName", "type": "text", "value": "Acme Industries Ltd", "metadata": { "extracted": true, "confidence": 1.0, "page": 1, "placement": { "x": 43, "y": 12, "width": 22, "height": 4 } } }, { "id": "field_02", "name": "invoiceNumber", "type": "text", "value": "INV-0042", "metadata": { "extracted": true, "confidence": 0.98, "page": 1, "placement": { "x": 316, "y": 48, "width": 147, "height": 10 } } }, { "id": "field_03", "name": "totalAmount", "type": "text", "value": "1,024.33 USD", "metadata": { "extracted": true, "confidence": 0.99, "page": 1, "placement": { "x": 316, "y": 209, "width": 147, "height": 10 } } } ] } } } ``` ### `document-insights.extraction.failed` Delivered when a Document Insights extraction reaches `FAILED`. `DOCUMENT_NOT_ROUTED` means no workspace configuration matched; verify `labels.docType` or default routing before retrying. `DOCUMENT_EXTRACTION_FAILED` means processing or extracted-data validation could not complete and may be retried with backoff when the cause is temporary. ```json { "eventId": "evt_01JY7MAFAILED00000000000001", "eventType": "document-insights.extraction.failed", "occurredAt": "2026-04-07T10:18:00Z", "apiVersion": "v1", "data": { "extractionId": "69654f0bc073ef404baec650", "status": "FAILED", "outputAvailable": false, "createdAt": "2026-04-07T10:05:10Z", "updatedAt": "2026-04-07T10:18:00Z", "completedAt": "2026-04-07T10:18:00Z", "error": { "code": "DOCUMENT_EXTRACTION_FAILED", "message": "The document could not be processed." }, "labels": {}, "document": { "fileId": "file_01JY7M4ZVX5R1P3M3Q0TA1S7ZZ", "fileName": "scan-corrupted.pdf", "mimeType": "application/pdf", "size": 1024, "pageCount": null } } } ``` ### `document-insights.extraction.rejected` Delivered when a Document Insights extraction reaches `REJECTED`. Rejection occurs when the document cannot be accepted, for example because it is broken, empty, duplicate, uses an unsupported format, or uses an unsupported language. Read `error.message` for the document-specific reason. ```json { "eventId": "evt_01JY7MREJECT0000000000001", "eventType": "document-insights.extraction.rejected", "occurredAt": "2026-04-07T10:06:00Z", "apiVersion": "v1", "data": { "extractionId": "69654f0bc073ef404baec651", "status": "REJECTED", "outputAvailable": false, "createdAt": "2026-04-07T10:05:55Z", "updatedAt": "2026-04-07T10:06:00Z", "completedAt": "2026-04-07T10:06:00Z", "error": { "code": "DOCUMENT_REJECTED", "message": "Duplicate document. Original document ID: 69654f0bc073ef404baec600" }, "labels": { "customerDocumentId": "doc-42" }, "document": { "fileId": "file_01JY7M4ZVX5R1P3M3Q0TA1S7ZM", "fileName": "invoice.pdf", "mimeType": "application/pdf", "size": 63877, "pageCount": 1 } } } ``` --- ## Workflow events ### `workflow.run.completed` Delivered when a workflow run reaches `COMPLETED`. The `data` payload includes the full run state, step-level outputs, and nested run summaries where applicable. `steps[*].output` is passed through from Plextera Studio, so its property names and enum casing are step-specific. Internal values such as `APPLICATION_PDF` may appear there and are not normalized. For `document_insights` steps, treat `extractionId` as the stable correlation field and use the Document Insights extraction endpoint for the canonical, typed result. ```json { "eventId": "evt_01JY7MRUNCOMP000000000001", "eventType": "workflow.run.completed", "occurredAt": "2026-04-07T10:25:30Z", "apiVersion": "v1", "data": { "runId": "69d224901610662a576cd7e6", "workflowId": "invoice-processing", "status": "COMPLETED", "createdAt": "2026-04-07T10:23:00Z", "updatedAt": "2026-04-07T10:25:30Z", "startedAt": "2026-04-07T10:23:02Z", "completedAt": "2026-04-07T10:25:30Z", "error": null, "workflow": { "id": "invoice-processing", "name": "Invoice Processing" }, "progress": { "stepsCompleted": 3, "stepsTotal": 3 }, "durationMs": 148000, "computedDurationMs": 142000, "steps": [ { "id": "step_01", "name": "Extract Invoice", "type": "document_insights", "status": "COMPLETED", "message": null, "output": { "extractionId": "69654f0bc073ef404baec649", "fileName": "invoice.pdf", "fields": [ { "id": "field_01", "name": "vendorName", "type": "TEXT", "value": "Acme Industries Ltd" } ], "metaAttributes": { "recordId": "69654f0bc073ef404baec649" }, "document": { "id": "69d224901610662a576cd800", "fileName": "invoice.pdf", "mimeType": "APPLICATION_PDF", "source": "DOCUMENT_INSIGHTS", "size": 126 } }, "nestedRuns": { "count": 0, "data": [] } } ] } } ``` ### `workflow.run.failed` Delivered when a workflow run reaches `FAILED` or `CLOSED`. For `FAILED`, the `data.error` field describes the failure. A run closed in Plextera Studio can omit `data.error`; use `data.status` and `data.steps` to understand its last known state. ```json { "eventId": "evt_01JY7MRUNFAIL000000000001", "eventType": "workflow.run.failed", "occurredAt": "2026-04-07T10:26:10Z", "apiVersion": "v1", "data": { "runId": "69d224901610662a576cd7e7", "workflowId": "invoice-processing", "status": "FAILED", "createdAt": "2026-04-07T10:23:00Z", "updatedAt": "2026-04-07T10:26:10Z", "startedAt": "2026-04-07T10:23:02Z", "completedAt": "2026-04-07T10:26:10Z", "error": { "code": "WORKFLOW_RUN_FAILED", "message": "Workflow run failed due to an error in step \"Send to ERP\"." }, "workflow": { "id": "invoice-processing", "name": "Invoice Processing" }, "progress": { "stepsCompleted": 2, "stepsTotal": 3 }, "durationMs": 188000, "computedDurationMs": 180000, "steps": [ { "id": "step_03", "name": "Send to ERP", "type": "web_function", "status": "FAILED", "message": "HTTP 503 from https://erp.example.com/api/invoices after 3 retries.", "output": null, "nestedRuns": { "count": 0, "data": [] } } ] } } ``` --- ## Event type summary | Event type | Triggered when | `data.output` present | | ---------------------------------------- | ----------------------------------------- | ----------------------------------------------------------------- | | `document-insights.extraction.completed` | Document extraction reaches `COMPLETED` | Yes, `ExtractionOutput` | | `document-insights.extraction.failed` | Document extraction reaches `FAILED` | No | | `document-insights.extraction.rejected` | Document extraction reaches `REJECTED` | No | | `workflow.run.completed` | Workflow run reaches `COMPLETED` | Step outputs in `steps` | | `workflow.run.failed` | Workflow run reaches `FAILED` or `CLOSED` | No top-level output; failed or closed step details are in `steps` |