Webhook Integration

Receive real-time notifications when your document processing is complete. Configure webhooks to automatically receive extracted data in your application.

Overview

The platform processes uploaded images and PDF files asynchronously. Instead of waiting for processing to finish, users submit a job request and receive the final result automatically through a configured webhook URL.

Key Benefits

  • ✓ Real-time result delivery via webhook
  • ✓ No need for API polling - results are pushed to you
  • ✓ Automated integration with your system
  • ✓ Fast, non-blocking job submission
  • ✓ Supports images, multi-page PDFs, and ZIP batch uploads

How It Works

1. Configure Your Webhook

Configure a webhook URL from the frontend dashboard for your template. This URL is saved with the template and will be used to deliver processing results. You can also set custom headers for authentication.

2. Submit a Processing Job

Submit a job using the POST /process-job API with:

  • template_id - UUID of the template to use
  • actual_image - Image, PDF, or ZIP file (base64 or file upload)
  • static_values - (Optional) Key-value pairs to include with the result

The system creates a unique job_id and queues the job with status NEW.

📦 ZIP File Batch Processing

You can upload a ZIP file containing multiple documents. Each file in the ZIP will be processed separately and trigger its own webhook request. Important: Files must be placed in the root of the ZIP archive, not inside folders.

3. Background Processing

The uploaded file is stored securely in S3 and queued for processing. During this time the job status is updated to PROCESSING. Credits are deducted based on the document type (1 credit per page for multi-page PDFs).

4. Webhook Result Delivery

Once processing is completed, a POST request is sent to your configured webhook URL with the extracted data in JSON format. The file is automatically deleted from storage after successful delivery.

For ZIP files: Each document in the ZIP archive triggers a separate webhook request, allowing you to process batch uploads efficiently.

API Reference

POST /process-job

Submit a document for asynchronous processing with webhook delivery.

Authentication

Requires API key in the x-auth header.

JSON Body

{
  "template_id": "550e8400-e29b-41d4-a716-446655440000",
  "actual_image": "<base64-encoded-image-or-pdf>",
  "static_values": {              // Optional
    "company_name": "Acme Corp"
  }
}

Multipart Form Data

template_id: 550e8400-e29b-41d4-a716-446655440000
actual_image: [file upload]
static_values: {"company_name": "Acme Corp"}  // Optional

Response (202 Accepted)

{
  "job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "template_id": "550e8400-e29b-41d4-a716-446655440000",
  "static_values": {
    "company_name": "Acme Corp"
  }
}

GET /job-status

Check the current status of a processing job. 

{
  "job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "template_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "PROCESSING"
}
Possible Status Values:
Status Description
NEW Job has been created and is queued for processing
UNZIPPING FILE Extracting files from uploaded ZIP archive
UNZIP FILE SUCCESS ZIP archive extraction completed successfully
UNZIP FILE FAILED ZIP archive extraction failed
PROCESSING IMAGE Processing document images for data extraction
PROCESS IMAGE SUCCESS Image processing completed successfully
PROCESS IMAGE FAILED Image processing failed
SUCCESS Job completed successfully, results are ready
FAILED Job processing failed

Webhook Payload

Success Payload

When processing is complete, the webhook receives a POST request with the following structure:

{
  "job_id": "3a931133-141f-4c58-aacb-ee55cb6d8188",
  "template_id": "7290a263-96bf-4cf3-865c-e2a1c81f9741",
  "static_values": {
    "company_name": "Acme Corp"
  },
  "result": {
    // Extracted data based on your template fields
    "field_1": "extracted_value_1",
    "field_2": "extracted_value_2",
    "field_3": "extracted_value_3",
    ...
  }
}

Note: The result object contains extracted data based on your template configuration.

Security & Reliability

  • 🔒 API authentication required for job submission
  • 🔒 Webhook URLs and headers stored securely
  • 🔒 Automatic retry mechanism for failed webhooks
  • 🔒 Files automatically deleted after processing
  • 🔒 Designed for high-scale workloads

Alternative: Job Results API

As an alternative to webhooks, you can retrieve processed results using the POST /v1/job-results endpoint. This is useful when you prefer to poll for results or need to retrieve results at a later time.

Output Formats

  • • json - Structured JSON response
  • • csv - CSV format for spreadsheets

Request Parameters

  • • job_id - UUID of the job
  • • result_format - json or csv

⏱️ 24-Hour Retention: Job results are stored for 24 hours after processing completion. Make sure to retrieve your results within this window. After 24 hours, results are automatically deleted and cannot be recovered.