Event Types & Payloads

This page is the complete reference for every webhook event Ocriva can emit. Each section describes the event, lists the fields in the payload object, and provides a realistic JSON example.

Common Payload Structure

Every webhook delivery — regardless of event type — shares the same outer envelope:

{
  "eventType": "document.processed",
  "eventId": "evt_1743418800000_abc123",
  "timestamp": "2026-03-31T12:00:00.000Z",
  "organizationId": "org_abc123",
  "projectId": "proj_xyz789",
  "payload": {
    // event-specific fields
  }
}

Field	Type	Description
`eventType`	`string`	The event that triggered this webhook (e.g. `document.processed`)
`eventId`	`string`	Unique identifier for this delivery attempt
`timestamp`	`string`	ISO 8601 UTC timestamp of when the event occurred
`organizationId`	`string`	ID of the organization that owns the resource
`projectId`	`string`	ID of the project the resource belongs to
`payload`	`object`	Event-specific data (see each event section below)

NOTE

The eventId uses the format evt_{unixMs}_{random6chars} — for example evt_1743418800000_abc123. The unix timestamp component reflects when the event was created, not when the delivery was attempted.

TIP

Use eventId to implement idempotent event handling. Store processed event IDs and skip re-processing if you receive the same ID twice — this protects you from duplicate deliveries caused by retries.

Document Events

Document events fire when individual files move through the processing pipeline.

`document.uploaded`

Fires immediately when a file is successfully uploaded to Ocriva, before AI processing begins.

Payload fields:

Field	Type	Description
`id`	`string`	Upload record ID
`fileName`	`string`	Original file name
`fileSize`	`number`	File size in bytes
`mimeType`	`string`	MIME type (e.g. `application/pdf`)
`status`	`string`	Always `uploaded` at this stage
`templateId`	`string`	ID of the template assigned for processing
`uploadedBy`	`string`	User ID who initiated the upload
`createdAt`	`string`	ISO 8601 UTC timestamp

Example:

{
  "eventType": "document.uploaded",
  "eventId": "evt_1743418800000_upl001",
  "timestamp": "2026-03-31T11:59:00.000Z",
  "organizationId": "org_abc123",
  "projectId": "proj_xyz789",
  "payload": {
    "id": "doc_upl_001",
    "fileName": "invoice_march.pdf",
    "fileSize": 204800,
    "mimeType": "application/pdf",
    "status": "uploaded",
    "templateId": "tmpl_invoice_v2",
    "uploadedBy": "user_wicha01",
    "createdAt": "2026-03-31T11:59:00.000Z"
  }
}

`document.processed`

Fires when a document finishes AI processing successfully. This is the most commonly used event — it carries the extracted data your downstream systems need.

Payload fields:

Field	Type	Description
`id`	`string`	Upload record ID
`fileName`	`string`	Original file name
`status`	`string`	Always `completed`
`extractedData`	`object`	The structured data extracted by the AI
`confidence`	`number`	Extraction confidence score (0–1)
`processingTime`	`number`	Time taken to process in milliseconds
`processedAt`	`string`	ISO 8601 UTC timestamp of completion

Example:

{
  "eventType": "document.processed",
  "eventId": "evt_1743418800000_prc002",
  "timestamp": "2026-03-31T12:00:03.241Z",
  "organizationId": "org_abc123",
  "projectId": "proj_xyz789",
  "payload": {
    "id": "doc_upl_001",
    "fileName": "invoice_march.pdf",
    "status": "completed",
    "extractedData": {
      "invoiceNumber": "INV-2026-0331",
      "vendor": "Acme Supplies Co.",
      "vendorTaxId": "0105560012345",
      "customer": "Beta Corp Ltd.",
      "issueDate": "2026-03-31",
      "dueDate": "2026-04-30",
      "subtotal": 14400.00,
      "vatAmount": 1008.00,
      "totalAmount": 15408.00,
      "currency": "THB",
      "lineItems": [
        {
          "description": "Cloud Storage (March)",
          "quantity": 12,
          "unitPrice": 1200.00,
          "amount": 14400.00
        }
      ]
    },
    "confidence": 0.97,
    "processingTime": 3241,
    "processedAt": "2026-03-31T12:00:03.241Z"
  }
}

`document.failed`

Fires when a document could not be processed successfully. Use this event to trigger error handling, alerting, or manual review workflows.

Payload fields:

Field	Type	Description
`id`	`string`	Upload record ID
`fileName`	`string`	Original file name
`status`	`string`	Always `failed`
`errorMessage`	`string`	Human-readable description of what went wrong
`processingTime`	`number`	Time elapsed before failure in milliseconds

Example:

{
  "eventType": "document.failed",
  "eventId": "evt_1743418900000_fail003",
  "timestamp": "2026-03-31T12:01:40.000Z",
  "organizationId": "org_abc123",
  "projectId": "proj_xyz789",
  "payload": {
    "id": "doc_upl_002",
    "fileName": "corrupted_scan.pdf",
    "status": "failed",
    "errorMessage": "Unable to extract text: document appears to be a scanned image with insufficient resolution (below 150 DPI).",
    "processingTime": 1820
  }
}

Batch Events

Batch events fire when groups of documents are uploaded or finish processing together.

`batch.uploaded`

Fires when a batch upload operation completes — all files in the batch have been received by Ocriva and queued for processing.

Payload fields:

Field	Type	Description
`batchId`	`string`	Unique batch identifier
`name`	`string`	Batch name as provided at upload time
`totalFiles`	`number`	Total number of files in the batch
`templateId`	`string`	Template applied to all files in this batch
`uploadedBy`	`string`	User ID who initiated the batch upload
`createdAt`	`string`	ISO 8601 UTC timestamp
`uploadIds`	`string[]`	Array of individual upload record IDs

Example:

{
  "eventType": "batch.uploaded",
  "eventId": "evt_1743418800000_bat004",
  "timestamp": "2026-03-31T12:00:00.000Z",
  "organizationId": "org_abc123",
  "projectId": "proj_xyz789",
  "payload": {
    "batchId": "batch_march_invoices",
    "name": "March 2026 Invoices",
    "totalFiles": 47,
    "templateId": "tmpl_invoice_v2",
    "uploadedBy": "user_wicha01",
    "createdAt": "2026-03-31T12:00:00.000Z",
    "uploadIds": [
      "doc_upl_101",
      "doc_upl_102",
      "doc_upl_103"
    ]
  }
}

`batch.completed`

Fires when every file in a batch has finished processing (either successfully or with failures). Use this event to trigger batch-level reporting or aggregation.

Payload fields:

Field	Type	Description
`batchId`	`string`	Unique batch identifier
`name`	`string`	Batch name
`totalFiles`	`number`	Total number of files submitted
`completedFiles`	`number`	Number of files that processed successfully
`failedFiles`	`number`	Number of files that failed
`status`	`string`	`completed` if all succeeded, `partial` if some failed
`completedAt`	`string`	ISO 8601 UTC timestamp of when the last file finished

Example:

{
  "eventType": "batch.completed",
  "eventId": "evt_1743422400000_bat005",
  "timestamp": "2026-03-31T13:00:00.000Z",
  "organizationId": "org_abc123",
  "projectId": "proj_xyz789",
  "payload": {
    "batchId": "batch_march_invoices",
    "name": "March 2026 Invoices",
    "totalFiles": 47,
    "completedFiles": 45,
    "failedFiles": 2,
    "status": "partial",
    "completedAt": "2026-03-31T13:00:00.000Z"
  }
}

Template Events

Template events fire when templates in your organization are created, modified, or removed. These are useful for syncing template metadata to external systems or audit logging.

`template.created`

Fires when a new template is created in the organization. Use this event to sync template metadata to external systems or initialize downstream configuration.

Payload fields:

Field	Type	Description
`id`	`string`	Unique template identifier
`name`	`string`	Template display name
`description`	`string`	Human-readable description of what the template extracts
`projectId`	`string`	ID of the project this template belongs to
`resultFormat`	`string`	Output format configured for this template (e.g. `json`, `csv`)
`createdBy`	`string`	User ID who created the template
`createdAt`	`string`	ISO 8601 UTC timestamp of creation

Example:

{
  "eventType": "template.created",
  "eventId": "evt_1743418800000_tpl006",
  "timestamp": "2026-03-31T12:00:00.000Z",
  "organizationId": "org_abc123",
  "projectId": "proj_xyz789",
  "payload": {
    "id": "tmpl_invoice_v2",
    "name": "Invoice Extractor v2",
    "description": "Extracts vendor, line items, totals, and tax details from Thai-language invoices.",
    "projectId": "proj_xyz789",
    "resultFormat": "json",
    "createdBy": "user_wicha01",
    "createdAt": "2026-03-31T12:00:00.000Z"
  }
}

`template.updated`

Fires when any field on a template is updated — including schema changes, model configuration changes, or name/description edits.

Payload fields:

Field	Type	Description
`id`	`string`	Unique template identifier
`name`	`string`	Template display name (after update)
`description`	`string`	Template description (after update)
`projectId`	`string`	ID of the project this template belongs to
`resultFormat`	`string`	Output format configured for this template
`updatedBy`	`string`	User ID who made the update
`updatedAt`	`string`	ISO 8601 UTC timestamp of the update
`changes`	`string[]`	Array of field names that were modified in this update

Example:

{
  "eventType": "template.updated",
  "eventId": "evt_1743422400000_tpl007",
  "timestamp": "2026-03-31T13:00:00.000Z",
  "organizationId": "org_abc123",
  "projectId": "proj_xyz789",
  "payload": {
    "id": "tmpl_invoice_v2",
    "name": "Invoice Extractor v2",
    "description": "Extracts vendor, line items, totals, tax details, and payment terms from Thai-language invoices.",
    "projectId": "proj_xyz789",
    "resultFormat": "json",
    "updatedBy": "user_wicha01",
    "updatedAt": "2026-03-31T13:00:00.000Z",
    "changes": ["description", "resultFormat"]
  }
}

`template.deleted`

Fires when a template is deleted. The payload retains enough information to reference the removed template even after it no longer exists in the system — useful for audit logging and cleaning up external references.

Payload fields:

Field	Type	Description
`id`	`string`	Unique identifier of the deleted template
`name`	`string`	Display name of the deleted template
`projectId`	`string`	ID of the project this template belonged to
`deletedBy`	`string`	User ID who deleted the template
`deletedAt`	`string`	ISO 8601 UTC timestamp of deletion

Example:

{
  "eventType": "template.deleted",
  "eventId": "evt_1743426000000_tpl008",
  "timestamp": "2026-03-31T14:00:00.000Z",
  "organizationId": "org_abc123",
  "projectId": "proj_xyz789",
  "payload": {
    "id": "tmpl_invoice_v1",
    "name": "Invoice Extractor v1",
    "projectId": "proj_xyz789",
    "deletedBy": "user_wicha01",
    "deletedAt": "2026-03-31T14:00:00.000Z"
  }
}

Documents

Event Types & Payloads

Event Types & Payloads

Common Payload Structure

Document Events

`document.uploaded`

`document.processed`

`document.failed`

Batch Events

`batch.uploaded`

`batch.completed`

Template Events

`template.created`

`template.updated`

`template.deleted`

Table of Contents