6 min read

Webhook Event Types

Name: DocuRift Document Extraction
Brand: DocuRift
Price: 4 INR
Availability: InStock

Complete reference of all webhook events with payload examples

DocuRift sends webhook notifications for various events during document processing. This page documents all available event types and their payloads.

Event Structure

All webhook events follow a consistent structure:

event-structure.json

{
"id": "evt_abc123def456ghi789",
"type": "document.processing.completed",
"apiVersion": "2024-01-26",
"createdAt": "2024-01-26T10:30:00.000Z",
"data": {
  // Event-specific payload
}
}

Common Fields

Parameter	Type	Description
`id`	`string`	Unique identifier for this event. Use for deduplication.
`type`	`string`	The event type (e.g., document.processing.completed)
`apiVersion`	`string`	API version used to generate this event
`createdAt`	`string`	ISO 8601 timestamp when the event was created
`data`	`object`	Event-specific payload containing relevant information

Document Events

document.processing.started

Triggered when document processing begins.

document.processing.started

{
"id": "evt_abc123def456ghi789",
"type": "document.processing.started",
"apiVersion": "2024-01-26",
"createdAt": "2024-01-26T10:30:00.000Z",
"data": {
  "documentId": "doc_1234567890abcdef",
  "organizationId": "org_xyz789",
  "fileName": "invoice-2024-001.pdf",
  "fileSize": 245678,
  "mimeType": "application/pdf",
  "documentType": "invoice",
  "pageCount": 2,
  "metadata": {
    "uploadedBy": "user_abc123",
    "source": "api"
  }
}
}

Data Fields

Parameter	Type	Description
`documentId`	`string`	Unique identifier for the document
`organizationId`	`string`	Organization that owns this document
`fileName`	`string`	Original file name
`fileSize`	`number`	File size in bytes
`mimeType`	`string`	MIME type of the uploaded file
`documentType`	`string`	Document type (invoice, receipt, contract, etc.)
`pageCount`	`number`	Number of pages in the document
`metadata`	`object`	Additional metadata about the upload

document.processing.completed

Triggered when document processing completes successfully. This event contains the extracted data.

document.processing.completed

{
"id": "evt_def456ghi789jkl012",
"type": "document.processing.completed",
"apiVersion": "2024-01-26",
"createdAt": "2024-01-26T10:30:15.000Z",
"data": {
  "documentId": "doc_1234567890abcdef",
  "organizationId": "org_xyz789",
  "fileName": "invoice-2024-001.pdf",
  "documentType": "invoice",
  "status": "completed",
  "processingTimeMs": 2340,
  "creditsUsed": 2,
  "result": {
    "vendor": {
      "name": "Acme Shipping Co.",
      "address": "123 Logistics Way, Los Angeles, CA 90001",
      "taxId": "12-3456789"
    },
    "invoiceNumber": "INV-2024-001",
    "invoiceDate": "2024-01-15",
    "dueDate": "2024-02-15",
    "lineItems": [
      {
        "description": "Ocean Freight - Shanghai to LA",
        "quantity": 1,
        "unitPrice": 2500.00,
        "total": 2500.00
      },
      {
        "description": "Customs Clearance",
        "quantity": 1,
        "unitPrice": 350.00,
        "total": 350.00
      }
    ],
    "subtotal": 2850.00,
    "tax": 256.50,
    "total": 3106.50,
    "currency": "USD"
  },
  "confidence": 0.97,
  "warnings": []
}
}

Data Fields

Parameter	Type	Description
`documentId`	`string`	Unique identifier for the document
`status`	`string`	Always "completed" for this event
`processingTimeMs`	`number`	Processing duration in milliseconds
`creditsUsed`	`number`	Number of credits consumed
`result`	`object`	Extracted data (structure varies by document type)
`confidence`	`number`	Overall confidence score (0-1)
`warnings`	`array`	Any warnings during extraction (e.g., low confidence fields)

💡

Result Structure

The result object structure varies based on the document type. See our Document Types reference for type-specific schemas.

document.processing.failed

Triggered when document processing fails due to an error.

document.processing.failed

{
"id": "evt_ghi789jkl012mno345",
"type": "document.processing.failed",
"apiVersion": "2024-01-26",
"createdAt": "2024-01-26T10:30:05.000Z",
"data": {
  "documentId": "doc_1234567890abcdef",
  "organizationId": "org_xyz789",
  "fileName": "corrupted-file.pdf",
  "documentType": "invoice",
  "status": "failed",
  "error": {
    "code": "DOCUMENT_UNREADABLE",
    "message": "Unable to extract text from the document. The file may be corrupted or password-protected.",
    "details": {
      "reason": "pdf_parse_error",
      "page": 1
    }
  },
  "creditsUsed": 0,
  "retryable": true
}
}

Error Codes

| Code | Description | Retryable | |------|-------------|-----------| | DOCUMENT_UNREADABLE | Cannot read or parse the document | Yes | | UNSUPPORTED_FORMAT | File format not supported | No | | FILE_TOO_LARGE | Document exceeds size limits | No | | PAGE_LIMIT_EXCEEDED | Too many pages | No | | PROCESSING_TIMEOUT | Processing took too long | Yes | | INTERNAL_ERROR | Unexpected server error | Yes |

Job Events

Jobs represent batch operations containing multiple documents.

job.completed

Triggered when all documents in a batch job have been processed.

job.completed

{
"id": "evt_jkl012mno345pqr678",
"type": "job.completed",
"apiVersion": "2024-01-26",
"createdAt": "2024-01-26T10:35:00.000Z",
"data": {
  "jobId": "job_abc123def456",
  "organizationId": "org_xyz789",
  "status": "completed",
  "totalDocuments": 10,
  "successCount": 9,
  "failureCount": 1,
  "processingTimeMs": 45230,
  "creditsUsed": 18,
  "documents": [
    {
      "documentId": "doc_001",
      "status": "completed",
      "fileName": "invoice-001.pdf"
    },
    {
      "documentId": "doc_002",
      "status": "completed",
      "fileName": "invoice-002.pdf"
    },
    {
      "documentId": "doc_010",
      "status": "failed",
      "fileName": "invoice-010.pdf",
      "errorCode": "DOCUMENT_UNREADABLE"
    }
  ],
  "metadata": {
    "batchName": "January 2024 Invoices",
    "submittedBy": "user_abc123"
  }
}
}

Data Fields

Parameter	Type	Description
`jobId`	`string`	Unique identifier for the batch job
`totalDocuments`	`number`	Total documents in the batch
`successCount`	`number`	Documents processed successfully
`failureCount`	`number`	Documents that failed processing
`processingTimeMs`	`number`	Total job processing time
`documents`	`array`	Summary of each document in the batch

job.failed

Triggered when a batch job fails entirely (e.g., due to validation errors before processing starts).

job.failed

{
"id": "evt_mno345pqr678stu901",
"type": "job.failed",
"apiVersion": "2024-01-26",
"createdAt": "2024-01-26T10:30:02.000Z",
"data": {
  "jobId": "job_def456ghi789",
  "organizationId": "org_xyz789",
  "status": "failed",
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "Not enough credits to process 50 documents. Required: 100, Available: 25"
  },
  "totalDocuments": 50,
  "creditsRequired": 100,
  "creditsAvailable": 25
}
}

Job Error Codes

| Code | Description | |------|-------------| | INSUFFICIENT_CREDITS | Not enough credits to process all documents | | BATCH_TOO_LARGE | Too many documents in a single batch | | VALIDATION_FAILED | One or more documents failed validation | | QUOTA_EXCEEDED | Organization quota exceeded |

Subscribing to Events

When creating a webhook, specify which events you want to receive:

subscribe-events.bash

curl -X POST https://api.docurift.com/v1/webhooks \
-H "X-API-Key: frc_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
  "url": "https://your-domain.com/webhooks/docurift",
  "events": [
    "document.processing.started",
    "document.processing.completed",
    "document.processing.failed",
    "job.completed",
    "job.failed"
  ]
}'

Wildcard Subscriptions

Use wildcards to subscribe to event categories:

wildcard-events.json

{
"events": [
  "document.*",  // All document events
  "job.*"        // All job events
]
}

Or subscribe to all events:

all-events.json

{
"events": ["*"]
}

Event Delivery Order

⚠️

Event Order Not Guaranteed

While events are typically delivered in order, DocuRift does not guarantee event ordering. Your application should handle events arriving out of sequence.

For example, in rare cases, you might receive document.processing.completed before document.processing.started. Use the createdAt timestamp and document status to handle this correctly.

Event Deduplication

Events may be delivered more than once. Always deduplicate using the event id:

deduplication.js

const processedEvents = new Set();

function handleWebhook(event) {
// Skip if already processed
if (processedEvents.has(event.id)) {
  console.log('Duplicate event, skipping:', event.id);
  return;
}

// Mark as processed
processedEvents.add(event.id);

// Process the event
processEvent(event);
}

// In production, use Redis or a database instead of in-memory Set

Next Steps

Signature Verification - Verify webhook authenticity
Testing Webhooks - Test and debug your webhook integration
Webhook Setup - Configure webhook endpoints