Introduction

Events

Plextera can push product events to client-controlled webhook endpoints. This lets you react to job and run completions without polling.

Available events

EventDelivered when
document-insights.job.completedA Document Insights job reaches COMPLETED.
document-insights.job.failedA Document Insights job reaches FAILED.
document-insights.job.rejectedA Document Insights job reaches REJECTED.
workflow.run.completedA workflow run reaches COMPLETED.
workflow.run.failedA workflow run reaches FAILED.

Setup

1

Create an event subscription

Call POST /event-subscriptions with:

  • endpointUrl — the URL Plextera should POST events to
  • eventTypes — the event types to subscribe to
  • signingSecret — a secret used to sign deliveries (see Verifying signatures)
  • workflowId (optional) — filter workflow events to a specific workflow
  • documentInsightsOperation (optional) — filter Document Insights events to a specific operation (e.g. extract)
2

Implement the webhook endpoint

Your endpoint must return a 2xx response within the request timeout. Any non-2xx response is treated as a failure and retried.

3

Receive and verify events

Verify the X-Plextera-Signature header on each delivery before processing the payload.

Payload model

Every event uses a common envelope:

1{
2  "eventId": "evt_01JY7M9QWBWCPMZK5QJ7RSE9P4",
3  "eventType": "document-insights.job.completed",
4  "occurredAt": "2026-04-07T10:22:00Z",
5  "apiVersion": "v1",
6  "data": { ... }
7}

The data field contains the event-specific payload. See the Event Reference for full schemas and examples.

Delivery headers

Every webhook delivery includes:

HeaderDescription
X-Plextera-Delivery-IdUnique ID for this delivery attempt.
X-Plextera-Event-IdID of the event (stable across retry attempts).
X-Plextera-Event-TypeEvent type string.
X-Plextera-Event-Occurred-AtISO 8601 timestamp when the event occurred.
X-Plextera-Api-VersionAPI version (e.g. v1).
X-Plextera-SignatureHMAC-SHA256 signature for payload verification.

Verifying signatures

Each delivery is signed using the signingSecret you provided when creating the subscription. Verify the signature to confirm the delivery came from Plextera and the payload was not tampered with.

Signature format:

X-Plextera-Signature: t=<unix timestamp>,v1=<hex hmac-sha256>

Verification steps:

  1. Extract t (timestamp) and v1 (signature) from the header.
  2. Construct the signed payload: <t>.<raw request body>.
  3. Compute HMAC-SHA256 of the signed payload using your signingSecret.
  4. Compare your computed signature to v1 using a constant-time comparison.
  5. Optionally reject deliveries where t is more than a few minutes in the past (replay protection).

The signing secret is write-only — it is never returned in API responses. Store it securely. To rotate it, update the subscription with a new signingSecret; all subsequent deliveries will use the new value.

Delivery semantics

  • Any 2xx response marks the delivery as successful.
  • Non-2xx responses trigger retries with exponential backoff.
  • Plextera deduplicates terminal events per subscription — each job or run reaches a terminal state at most once, so at most one delivery is attempted per event type per subscription.

Next steps