Event Subscriptions

Event subscriptions let Plextera push product events to your webhook endpoint. Use them when your integration should react to completed, failed, or rejected processing without polling.

When to use events

Available events

Setup

$
curl -X POST https://api.plextera.com/api/public/v1/event-subscriptions \
>
  -H "Authorization: api-key YOUR_API_KEY" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "endpointUrl": "https://example.com/webhooks/plextera",
>
    "eventTypes": [
>
      "document-insights.extraction.completed",
>
      "document-insights.extraction.failed",
>
      "document-insights.extraction.rejected"
>
    ],
>
    "signingSecret": "whsec_your_secret"
>
  }'

Event payload model

Every event uses a common envelope:

1
{
2
  "eventId": "evt_01JY7M9QWBWCPMZK5QJ7RSE9P4",
3
  "eventType": "document-insights.extraction.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 complete schemas and examples.

Delivery headers

Every webhook delivery includes:

Verifying signatures

Each delivery is signed using the signingSecret you provided when creating the subscription. This confirms the delivery came from Plextera and that the payload was not modified.

Signature format:

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

Verification steps:

1. Extract t and v1 from the header.
2. Construct the signed payload: <t>.<raw request body>.
3. Compute HMAC-SHA256 using your signingSecret.
4. Compare the computed signature with v1 using a constant-time comparison.
5. Optionally reject old timestamps for replay protection.

1
import hashlib
2
import hmac
3
import time
4
5
6
def verify_signature(
7
    payload: bytes,
8
    header: str,
9
    secret: str,
10
    max_age_seconds: int = 300,
11
) -> bool:
12
    parts = dict(p.split("=", 1) for p in header.split(","))
13
    timestamp = int(parts["t"])
14
    signature = parts["v1"]
15
16
    if abs(time.time() - timestamp) > max_age_seconds:
17
        return False
18
19
    signed = f"{timestamp}.".encode() + payload
20
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
21
    return hmac.compare_digest(expected, signature)

Retry and idempotency

• Any 2xx response marks the delivery as successful.
• Non-2xx responses trigger retries with exponential backoff.
• The same eventId may be delivered more than once.
• Your webhook handler should be idempotent. Store processed eventId values or use your own deduplication key.
• If a document is reprocessed after a terminal state, a later terminal state can produce a new event.

Related reference

• Event Reference - webhook payload schemas and examples
• Event Subscriptions - create and manage subscriptions