DocuTray
API ReferenceDocuTray.com
Webhooks

Conversion Events

Docutray conversion webhooks — real-time callbacks fired while a document is processed, delivering the extracted structured data to your endpoint.

Conversion webhooks are sent during document processing when using a specific document type to extract structured data.

Conversion Events

Conversion Started (CONVERSION_STARTED)

Sent when document processing begins:

{
  "conversion_id": "clm123abc456def",
  "status": "PROCESSING",
  "request_timestamp": "2024-01-15T10:30:00.000Z",
  "document_type_code": "invoice",
  "original_filename": "invoice-001.pdf",
  "document_metadata": {
    "client_id": "ABC123",
    "department": "finance"
  }
}

Fields:

  • conversion_id (string): Unique conversion ID
  • status (string): Current status, always "PROCESSING" for this event
  • request_timestamp (string): ISO 8601 timestamp of when conversion started
  • document_type_code (string): Code of the document type used
  • original_filename (string, optional): Original name of the processed file
  • document_metadata (object, optional): Custom metadata sent with the conversion

Conversion Completed (CONVERSION_COMPLETED)

Sent when conversion finishes successfully:

{
  "conversion_id": "clm123abc456def",
  "status": "SUCCESS",
  "request_timestamp": "2024-01-15T10:30:00.000Z",
  "response_timestamp": "2024-01-15T10:30:15.000Z",
  "document_type_code": "invoice",
  "original_filename": "invoice-001.pdf",
  "document_metadata": {
    "client_id": "ABC123",
    "department": "finance"
  },
  "data": {
    "invoiceNumber": "INV-2024-001",
    "amount": 1250.00,
    "vendor": "ABC Company Inc.",
    "date": "2024-01-15"
  },
  "validation": {
    "valid": false,
    "errors": [
      {
        "field": "amount",
        "value": 1250,
        "rule": "equalsWithPrecision",
        "message": "El campo 'amount' debe ser igual a '1200' con 2 decimales de precisión, pero es '1250'",
        "code": "VALIDATION_ERROR",
        "severity": "error",
        "source": "rule"
      }
    ],
    "warnings": []
  }
}

Fields:

  • conversion_id (string): Unique conversion ID
  • status (string): Current status, always "SUCCESS" for this event
  • request_timestamp (string): ISO 8601 timestamp of when conversion started
  • response_timestamp (string): ISO 8601 timestamp of when conversion completed
  • document_type_code (string): Code of the document type used
  • original_filename (string, optional): Original name of the processed file
  • document_metadata (object, optional): Custom metadata sent with the conversion
  • data (object): Extracted data from the document according to the document type schema
  • validation (object or null): Result of checking data against the document type's JSON Schema and validation rules. It is informational and never changes status:
    • { "valid", "errors", "warnings" } when validation ran. errors and warnings are lists of issues with field, code, message, severity and source; see reading the results.
    • null when validation was skipped because the document type has no JSON Schema and no rules.
    • { "status": "error" } when validation could not be completed or no validation record exists. No internal details are included.

Conversion Failed (CONVERSION_FAILED)

Sent when conversion fails:

{
  "conversion_id": "clm123abc456def",
  "status": "ERROR",
  "request_timestamp": "2024-01-15T10:30:00.000Z",
  "response_timestamp": "2024-01-15T10:30:10.000Z",
  "document_type_code": "invoice",
  "original_filename": "invoice-001.pdf",
  "document_metadata": {
    "client_id": "ABC123",
    "department": "finance"
  },
  "error": "Error during OCR processing: Unable to process image"
}

Fields:

  • conversion_id (string): Unique conversion ID
  • status (string): Current status, always "ERROR" for this event
  • request_timestamp (string): ISO 8601 timestamp of when conversion started
  • response_timestamp (string): ISO 8601 timestamp of when conversion failed
  • document_type_code (string): Code of the document type used
  • original_filename (string, optional): Original name of the processed file
  • document_metadata (object, optional): Custom metadata sent with the conversion
  • error (string): Descriptive error message

Implementation Example

app.post('/webhooks/docutray', (req, res) => {
  const eventType = req.headers['x-docutray-event'];
  const data = JSON.parse(req.body);

  switch (eventType) {
    case 'CONVERSION_STARTED':
      console.log(`Conversion started: ${data.conversion_id}`);
      // Update database with "processing" status
      break;

    case 'CONVERSION_COMPLETED':
      console.log(`Conversion completed: ${data.conversion_id}`);
      console.log('Extracted data:', data.data);
      if (data.validation?.valid === false) {
        // Route to manual review; the conversion itself succeeded
        console.log('Validation errors:', data.validation.errors.map((e) => e.message));
      }
      // Save extracted data to database
      // Send notification to user
      break;

    case 'CONVERSION_FAILED':
      console.log(`Conversion failed: ${data.conversion_id}`);
      console.log('Error:', data.error);
      // Log error and notify user
      break;
  }

  res.status(200).send('OK');
});

Webhook Configuration

Configure and manage Docutray webhooks — register endpoints, choose events, and secure delivery so your app reacts to document processing in real time.

Identification Events

Docutray identification webhooks — real-time callbacks fired while a document's type is auto-detected, delivering the result to your endpoint.

On this page

Conversion EventsConversion Started (CONVERSION_STARTED)Conversion Completed (CONVERSION_COMPLETED)Conversion Failed (CONVERSION_FAILED)Implementation ExampleRelated pages