Event Reference

The Event Reference documents webhook payloads delivered by Plextera to endpoints configured through 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.

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:

1{
2  "eventId": "evt_01JY7M9QWBWCPMZK5QJ7RSE9P4",
3  "eventType": "document-insights.extraction.completed",
4  "occurredAt": "2026-04-07T10:22:00Z",
5  "apiVersion": "v1",
6  "data": { "...": "event-specific payload" }
7}
FieldDescription
eventIdUnique event identifier. Stable across retry attempts for the same event.
eventTypeEvent type string.
occurredAtUTC ISO 8601 timestamp when the terminal state was reached.
apiVersionAPI version used to format the payload, for example v1.
dataEvent-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.

1{
2  "eventId": "evt_01JY7M9QWBWCPMZK5QJ7RSE9P4",
3  "eventType": "document-insights.extraction.completed",
4  "occurredAt": "2026-04-07T10:22:00Z",
5  "apiVersion": "v1",
6  "data": {
7    "extractionId": "69654f0bc073ef404baec649",
8    "status": "COMPLETED",
9    "outputAvailable": true,
10    "createdAt": "2026-04-07T10:05:04Z",
11    "updatedAt": "2026-04-07T10:22:00Z",
12    "completedAt": "2026-04-07T10:22:00Z",
13    "labels": { "customerDocumentId": "doc-42", "docType": "invoice" },
14    "document": {
15      "fileId": "file_01JY7M4ZVX5R1P3M3Q0TA1S7ZM",
16      "fileName": "invoice.pdf",
17      "mimeType": "application/pdf",
18      "size": 63877,
19      "pageCount": 1
20    },
21    "output": {
22      "fieldCount": 3,
23      "fields": [
24        {
25          "id": "field_01",
26          "name": "vendorName",
27          "type": "text",
28          "value": "Acme Industries Ltd",
29          "metadata": {
30            "extracted": true,
31            "confidence": 1.0,
32            "page": 1,
33            "placement": { "x": 43, "y": 12, "width": 22, "height": 4 }
34          }
35        },
36        {
37          "id": "field_02",
38          "name": "invoiceNumber",
39          "type": "text",
40          "value": "INV-0042",
41          "metadata": {
42            "extracted": true,
43            "confidence": 0.98,
44            "page": 1,
45            "placement": { "x": 316, "y": 48, "width": 147, "height": 10 }
46          }
47        },
48        {
49          "id": "field_03",
50          "name": "totalAmount",
51          "type": "text",
52          "value": "1,024.33 USD",
53          "metadata": {
54            "extracted": true,
55            "confidence": 0.99,
56            "page": 1,
57            "placement": { "x": 316, "y": 209, "width": 147, "height": 10 }
58          }
59        }
60      ]
61    }
62  }
63}

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.

1{
2  "eventId": "evt_01JY7MAFAILED00000000000001",
3  "eventType": "document-insights.extraction.failed",
4  "occurredAt": "2026-04-07T10:18:00Z",
5  "apiVersion": "v1",
6  "data": {
7    "extractionId": "69654f0bc073ef404baec650",
8    "status": "FAILED",
9    "outputAvailable": false,
10    "createdAt": "2026-04-07T10:05:10Z",
11    "updatedAt": "2026-04-07T10:18:00Z",
12    "completedAt": "2026-04-07T10:18:00Z",
13    "error": {
14      "code": "DOCUMENT_EXTRACTION_FAILED",
15      "message": "The document could not be processed."
16    },
17    "labels": {},
18    "document": {
19      "fileId": "file_01JY7M4ZVX5R1P3M3Q0TA1S7ZZ",
20      "fileName": "scan-corrupted.pdf",
21      "mimeType": "application/pdf",
22      "size": 1024,
23      "pageCount": null
24    }
25  }
26}

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.

1{
2  "eventId": "evt_01JY7MREJECT0000000000001",
3  "eventType": "document-insights.extraction.rejected",
4  "occurredAt": "2026-04-07T10:06:00Z",
5  "apiVersion": "v1",
6  "data": {
7    "extractionId": "69654f0bc073ef404baec651",
8    "status": "REJECTED",
9    "outputAvailable": false,
10    "createdAt": "2026-04-07T10:05:55Z",
11    "updatedAt": "2026-04-07T10:06:00Z",
12    "completedAt": "2026-04-07T10:06:00Z",
13    "error": {
14      "code": "DOCUMENT_REJECTED",
15      "message": "Duplicate document. Original document ID: 69654f0bc073ef404baec600"
16    },
17    "labels": { "customerDocumentId": "doc-42" },
18    "document": {
19      "fileId": "file_01JY7M4ZVX5R1P3M3Q0TA1S7ZM",
20      "fileName": "invoice.pdf",
21      "mimeType": "application/pdf",
22      "size": 63877,
23      "pageCount": 1
24    }
25  }
26}

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.

1{
2  "eventId": "evt_01JY7MRUNCOMP000000000001",
3  "eventType": "workflow.run.completed",
4  "occurredAt": "2026-04-07T10:25:30Z",
5  "apiVersion": "v1",
6  "data": {
7    "runId": "69d224901610662a576cd7e6",
8    "workflowId": "invoice-processing",
9    "status": "COMPLETED",
10    "createdAt": "2026-04-07T10:23:00Z",
11    "updatedAt": "2026-04-07T10:25:30Z",
12    "startedAt": "2026-04-07T10:23:02Z",
13    "completedAt": "2026-04-07T10:25:30Z",
14    "error": null,
15    "workflow": { "id": "invoice-processing", "name": "Invoice Processing" },
16    "progress": { "stepsCompleted": 3, "stepsTotal": 3 },
17    "durationMs": 148000,
18    "computedDurationMs": 142000,
19    "steps": [
20      {
21        "id": "step_01",
22        "name": "Extract Invoice",
23        "type": "document_insights",
24        "status": "COMPLETED",
25        "message": null,
26        "output": {
27          "extractionId": "69654f0bc073ef404baec649",
28          "fileName": "invoice.pdf",
29          "fields": [ { "id": "field_01", "name": "vendorName", "type": "TEXT", "value": "Acme Industries Ltd" } ],
30          "metaAttributes": { "recordId": "69654f0bc073ef404baec649" },
31          "document": { "id": "69d224901610662a576cd800", "fileName": "invoice.pdf", "mimeType": "APPLICATION_PDF", "source": "DOCUMENT_INSIGHTS", "size": 126 }
32        },
33        "nestedRuns": { "count": 0, "data": [] }
34      }
35    ]
36  }
37}

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.

1{
2  "eventId": "evt_01JY7MRUNFAIL000000000001",
3  "eventType": "workflow.run.failed",
4  "occurredAt": "2026-04-07T10:26:10Z",
5  "apiVersion": "v1",
6  "data": {
7    "runId": "69d224901610662a576cd7e7",
8    "workflowId": "invoice-processing",
9    "status": "FAILED",
10    "createdAt": "2026-04-07T10:23:00Z",
11    "updatedAt": "2026-04-07T10:26:10Z",
12    "startedAt": "2026-04-07T10:23:02Z",
13    "completedAt": "2026-04-07T10:26:10Z",
14    "error": {
15      "code": "WORKFLOW_RUN_FAILED",
16      "message": "Workflow run failed due to an error in step \"Send to ERP\"."
17    },
18    "workflow": { "id": "invoice-processing", "name": "Invoice Processing" },
19    "progress": { "stepsCompleted": 2, "stepsTotal": 3 },
20    "durationMs": 188000,
21    "computedDurationMs": 180000,
22    "steps": [
23      {
24        "id": "step_03",
25        "name": "Send to ERP",
26        "type": "web_function",
27        "status": "FAILED",
28        "message": "HTTP 503 from https://erp.example.com/api/invoices after 3 retries.",
29        "output": null,
30        "nestedRuns": { "count": 0, "data": [] }
31      }
32    ]
33  }
34}

Event type summary

Event typeTriggered whendata.output present
document-insights.extraction.completedDocument extraction reaches COMPLETEDYes, ExtractionOutput
document-insights.extraction.failedDocument extraction reaches FAILEDNo
document-insights.extraction.rejectedDocument extraction reaches REJECTEDNo
workflow.run.completedWorkflow run reaches COMPLETEDStep outputs in steps
workflow.run.failedWorkflow run reaches FAILED or CLOSEDNo top-level output; failed or closed step details are in steps