Steps Webhooks

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