Identification Events
Webhooks for automatic document type identification
Identification Webhooks
Identification webhooks are sent during the automatic document type identification process, where Docutray analyzes the document and determines its type among the specified options.
Identification Events
Identification Started (IDENTIFICATION_STARTED)
Sent when document identification process begins:
{
"identification_id": "idn_abc123xyz789",
"status": "PROCESSING",
"request_timestamp": "2024-01-15T10:30:00.000Z",
"original_filename": "unknown-document.pdf",
"document_metadata": {
"source": "email_attachment",
"received_date": "2024-01-15"
},
"document_type_code_options": ["invoice", "receipt", "purchase_order"]
}Fields:
identification_id(string): Unique identification IDstatus(string): Current status, always"PROCESSING"for this eventrequest_timestamp(string): ISO 8601 timestamp of when identification startedoriginal_filename(string, optional): Original file namedocument_metadata(object, optional): Custom metadata sent with the identificationdocument_type_code_options(array, optional): List of document type codes to identify among
Identification Completed (IDENTIFICATION_COMPLETED)
Sent when identification finishes successfully:
{
"identification_id": "idn_abc123xyz789",
"status": "SUCCESS",
"request_timestamp": "2024-01-15T10:30:00.000Z",
"response_timestamp": "2024-01-15T10:30:08.000Z",
"original_filename": "unknown-document.pdf",
"document_metadata": {
"source": "email_attachment",
"received_date": "2024-01-15"
},
"document_type": {
"code": "invoice",
"name": "Invoice",
"confidence": 0.95
},
"document_type_code_options": ["invoice", "receipt", "purchase_order"],
"alternatives": [
{
"code": "receipt",
"name": "Receipt",
"confidence": 0.78
},
{
"code": "purchase_order",
"name": "Purchase Order",
"confidence": 0.45
}
]
}Fields:
identification_id(string): Unique identification IDstatus(string): Current status, always"SUCCESS"for this eventrequest_timestamp(string): ISO 8601 timestamp of when identification startedresponse_timestamp(string): ISO 8601 timestamp of when identification completedoriginal_filename(string, optional): Original file namedocument_metadata(object, optional): Custom metadata sent with the identificationdocument_type(object): Identified document type with highest confidencecode(string): Document type codename(string): Document type nameconfidence(number): Identification confidence level (0-1)
document_type_code_options(array, optional): List of document type codes that were identified amongalternatives(array, optional): Alternative document types with their confidence levels
Identification Failed (IDENTIFICATION_FAILED)
Sent when identification fails:
{
"identification_id": "idn_abc123xyz789",
"status": "ERROR",
"request_timestamp": "2024-01-15T10:30:00.000Z",
"response_timestamp": "2024-01-15T10:30:05.000Z",
"original_filename": "unknown-document.pdf",
"document_metadata": {
"source": "email_attachment",
"received_date": "2024-01-15"
},
"error": "Unable to identify document type: image quality too low"
}Fields:
identification_id(string): Unique identification IDstatus(string): Current status, always"ERROR"for this eventrequest_timestamp(string): ISO 8601 timestamp of when identification startedresponse_timestamp(string): ISO 8601 timestamp of when identification failedoriginal_filename(string, optional): Original file namedocument_metadata(object, optional): Custom metadata sent with the identificationerror(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 'IDENTIFICATION_STARTED':
console.log(`Identification started: ${data.identification_id}`);
// Update database with "identifying" status
break;
case 'IDENTIFICATION_COMPLETED':
console.log(`Identification completed: ${data.identification_id}`);
console.log(`Identified type: ${data.document_type.code}`);
console.log(`Confidence: ${data.document_type.confidence}`);
// Save identified type to database
// If confidence is high, proceed with automatic conversion
if (data.document_type.confidence > 0.9) {
// Start automatic conversion
}
break;
case 'IDENTIFICATION_FAILED':
console.log(`Identification failed: ${data.identification_id}`);
console.log('Error:', data.error);
// Log error and request manual intervention
break;
}
res.status(200).send('OK');
});