Skip to main content

Asynchronous Processing Overview

Asynchronous processing allows you to upload lab report documents and receive immediate responses while the AI analysis happens in the background. This approach provides better user experience for interactive applications and enables you to handle multiple requests efficiently.

How Asynchronous Processing Works

  1. Upload Document — send a POST request with wait_on_process: false (default)
  2. Immediate Response — receive a response with status: "processing", and a record_id
  3. Background Processing — AI models analyze the document (typically 10–60 seconds)
  4. Get Results — receive webhook notification with an analysis report when finished

Getting Results

Webhooks

Configure a webhook URL to receive real-time notifications when analysis completes: Request:
Immediate Response:
Webhook Notification (when analysis completes):

Alternative: Manual Checking

If webhooks are not available in your environment, you can check the status using the GET /lab_reports/{lab_report_id} endpoint:

Webhook Configuration

Setup

Configure your webhook URL through the admin console. Your endpoint must:
  • Respond with HTTP 200 to acknowledge receipt
  • Handle POST requests with JSON payloads
  • Verify HMAC signatures for security
If requests fail, the system retries up to 5 times with exponential backoff.

Security

All webhook requests include HMAC SHA256 signature verification:
  • Headerx-body-signature contains the hex-encoded HMAC signature
  • Key — uses your application’s webhook signature key (configured in the admin console)
  • AlgorithmHMAC-SHA256(webhook_signature_key, request_body)
See Webhook Signature for more details.

Status Handling

Your webhook handler should handle different status values:
  • completed — analysis successful, lab report data are available
  • failed — analysis failed, check parsing_error field for details
When status is failed, check the parsing_error field for specific details about what prevented successful analysis.

Implementation Examples

For complete API specifications and additional configuration options, see the Implementation Guide.