Steps Events

Docutray step webhooks — real-time callbacks fired as individual workflow steps (conversion, identification, validation) execute in a pipeline.

Steps webhooks are sent during the execution of individual steps in document processing workflows. Each step can perform operations such as conversion, identification, or validation.

Steps Events

Step Started (`STEP_STARTED`)

Sent when step execution begins:

{
  "step_execution_id": "step_exec_xyz123",
  "step_id": "step_convert_invoice",
  "step_name": "Convert Invoice",
  "status": "PROCESSING",
  "request_timestamp": "2024-01-15T10:30:00.000Z",
  "document_metadata": {
    "batch_id": "batch_001",
    "priority": "high"
  }
}

Fields:

step_execution_id (string): Unique step execution ID
step_id (string): Step ID in the workflow
step_name (string): Descriptive name of the step
status (string): Current status, always "PROCESSING" for this event
request_timestamp (string): ISO 8601 timestamp of when step started
document_metadata (object, optional): Metadata of the document being processed

Step Completed (`STEP_COMPLETED`)

Sent when a step finishes successfully:

{
  "step_execution_id": "step_exec_xyz123",
  "step_id": "step_convert_invoice",
  "step_name": "Convert Invoice",
  "status": "completed",
  "request_timestamp": "2024-01-15T10:30:00.000Z",
  "response_timestamp": "2024-01-15T10:30:12.000Z",
  "document_metadata": {
    "batch_id": "batch_001",
    "priority": "high"
  },
  "data": {
    "invoiceNumber": "INV-2024-001",
    "amount": 1250.00,
    "vendor": "ABC Company Inc.",
    "date": "2024-01-15"
  },
  "identification": {
    "document_type": "invoice",
    "confidence": 0.95
  },
  "validation": {
    "errors": {
      "count": 0,
      "messages": []
    },
    "warnings": {
      "count": 1,
      "messages": ["Amount exceeds historical average"]
    }
  }
}

Fields:

step_execution_id (string): Unique step execution ID
step_id (string): Step ID in the workflow
step_name (string): Descriptive name of the step
status (string): Current status, always "completed" for this event
request_timestamp (string): ISO 8601 timestamp of when step started
response_timestamp (string): ISO 8601 timestamp of when step completed
document_metadata (object, optional): Metadata of the document being processed
data (object, optional): Processed document data (if step performed conversion)
identification (object, optional): Identification result (if step performed identification)
validation (object, optional): Validation result with errors and warnings

Step Failed (`STEP_FAILED`)

Sent when a step fails:

{
  "step_execution_id": "step_exec_xyz123",
  "step_id": "step_convert_invoice",
  "step_name": "Convert Invoice",
  "status": "failed",
  "request_timestamp": "2024-01-15T10:30:00.000Z",
  "response_timestamp": "2024-01-15T10:30:08.000Z",
  "document_metadata": {
    "batch_id": "batch_001",
    "priority": "high"
  },
  "error": "Validation failed: required field 'invoiceNumber' is missing"
}

Fields:

step_execution_id (string): Unique step execution ID
step_id (string): Step ID in the workflow
step_name (string): Descriptive name of the step
status (string): Current status, always "failed" for this event
request_timestamp (string): ISO 8601 timestamp of when step started
response_timestamp (string): ISO 8601 timestamp of when step failed
document_metadata (object, optional): Metadata of the document being processed
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 'STEP_STARTED':
      console.log(`Step started: ${data.step_name} (${data.step_execution_id})`);
      // Update UI with workflow progress
      break;

    case 'STEP_COMPLETED':
      console.log(`Step completed: ${data.step_name} (${data.step_execution_id})`);

      // Process data if available
      if (data.data) {
        console.log('Processed data:', data.data);
        // Save data to database
      }

      // Check validation results
      if (data.validation) {
        if (data.validation.errors.count > 0) {
          console.log('Validation errors:', data.validation.errors.messages);
          // Notify validation errors
        }
        if (data.validation.warnings.count > 0) {
          console.log('Warnings:', data.validation.warnings.messages);
          // Log warnings
        }
      }
      break;

    case 'STEP_FAILED':
      console.log(`Step failed: ${data.step_name} (${data.step_execution_id})`);
      console.log('Error:', data.error);
      // Stop workflow and notify error
      // Log failure for analysis
      break;
  }

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

Use cases

Monitoring complex workflows

Steps webhooks are ideal for monitoring the execution of multi-step workflows:

// Example: Track progress of a multi-step workflow
const flowProgress = {
  stepStates: {},
  totalSteps: 0,
  completedSteps: 0
};

function handleStepEvent(data, eventType) {
  const stepId = data.step_id;

  if (eventType === 'STEP_STARTED') {
    flowProgress.stepStates[stepId] = 'processing';
    flowProgress.totalSteps++;
  } else if (eventType === 'STEP_COMPLETED') {
    flowProgress.stepStates[stepId] = 'completed';
    flowProgress.completedSteps++;
  } else if (eventType === 'STEP_FAILED') {
    flowProgress.stepStates[stepId] = 'failed';
  }

  // Calculate progress percentage
  const progress = (flowProgress.completedSteps / flowProgress.totalSteps) * 100;
  console.log(`Workflow progress: ${progress}%`);
}

Validation and quality control

Use validation results to implement quality controls:

function handleValidationResults(validation) {
  // Stop processing if there are critical errors
  if (validation.errors.count > 0) {
    // Send to manual review
    sendToManualReview(validation.errors.messages);
    return;
  }

  // Warnings don't block the workflow
  if (validation.warnings.count > 0) {
    // Log for analysis but continue
    logWarnings(validation.warnings.messages);
  }

  // Continue to next step in workflow
  proceedToNextStep();
}

Steps Events

On this page