Webhooks Overview

Receive real-time notifications about events in your Parsurai account.

Parsurai webhooks allow your application to receive real-time HTTP POST notifications when events occur in your account, such as when an invoice extraction completes or a manual review session is finished.

Supported Event Types

Event Type	Description
`extraction.completed`	An invoice document has been successfully processed and structured data has been extracted.
`extraction.failed`	Processing of an invoice document failed due to a parsing error or unreadable layout.
`review.required`	Manual verification is required because extraction confidence was below the threshold.
`review.completed`	A human reviewer has completed manual verification and finalized the invoice fields.
`workflow.completed`	The entire document pipeline (including optional crop, split, and review) succeeded.
`workflow.failed`	The pipeline was aborted because one of the mandatory processing stages failed.

Payload Envelope

All webhooks are sent as application/json HTTP POST requests. The request body contains a JSON object wrapping the event metadata and the specific resource payload.

{
  "id": "evt_9f3b2c1d0e4a4f5b8c6d7e8f9a0b1c2d",
  "type": "extraction.completed",
  "version": "2026-06-01",
  "occurred_at": "2026-06-21T10:40:00Z",
  "tenant_id": "7f9c2f4e-9b1a-4c3d-8e5f-6a7b8c9d0e1f",
  "data": {
    "invoice_id": "a3a4c1de-1c1e-4b6f-9d2a-0f8e7d6c5b4a"
  }
}

Top-Level Fields

id: A unique identifier for this event (evt_...). Used for deduplication.
type: The event type string (e.g. extraction.completed).
version: The API envelope version matching the user's configuration.
occurred_at: ISO-8601 UTC timestamp of when the event originally happened.
tenant_id: The ID of your Parsurai workspace/account.
data: A payload object containing references or metadata relevant to the event. To protect sensitive customer data, outbound webhook payloads minimize PII and only include resource IDs. You can query the full resource details using our REST API or SDKs.

Delivery Policies & Security

HTTPS Protocol: In production, Parsurai only delivers webhooks to secure https:// URLs.
Port Restriction: Production endpoints must listen on port 443 (explicitly or implicitly). Other ports will be rejected to protect against Server-Side Request Forgery (SSRF).
IP Range (No Static IP): Parsurai does not route outbound webhooks through a static block of IP addresses. You should verify request signatures instead of whitelisting IPs.
Lease and Timeout: We expect your server to respond with a 2xx status code within 10 seconds for connection/read. If delivery fails or times out, a retry sequence will be initiated.
Soft-Delete History: When you delete a webhook endpoint, it is soft-deleted. The delivery history is preserved for auditing until the retention period prunes it.
Idempotency: Webhooks are delivered at-least-once. Your receiver must be idempotent by checking the id field before processing events.