Asynchronous Processing Overview
Asynchronous processing allows you to upload food images 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
- Upload Image: send a POST request with
wait_on_process: false
(default) - Immediate Response: receive a response with
status: "pending"
orstatus: "processing"
, and arecord_id
- Background Processing: AI models analyze the image (typically 4–30 seconds)
- 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:Alternative: Manual Checking
If webhooks are not available in your environment, you can check the status using theGET /nutrition_records/{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
Security
All webhook requests include HMAC SHA256 signature verification:- Header:
x-body-signature
contains the hex-encoded HMAC signature - Key: uses your application’s webhook signature key (configured in admin console)
- Algorithm:
HMAC-SHA256(webhook_signature_key, request_body)
Status Handling
Your webhook handler should handle different status values. For complete status definitions, see Processing Status. Whenstatus
is failed
, check the failure_reason
field for specific details about what prevented successful analysis.
Best Practices
1. Webhook Implementation
- Respond quickly: always respond with HTTP 200 immediately, then process data asynchronously
- Validate signatures: always verify the HMAC signature before processing webhook data
- Handle failures gracefully: check the status field and handle both success and failure cases
- Implement idempotency: use the
record_id
to avoid processing the same webhook multiple times
2. Error Handling
- Handle webhook delivery failures gracefully
- Store webhook secrets securely and never commit them to version control
- Implement retry logic for critical webhook processing
3. User Experience
- Show immediate feedback when image is uploaded (“Analysis in progress…”)
- Provide progress indicators during the 4-30 second processing window
- Handle both success and failure states in your UI
Use Cases
Asynchronous processing is ideal for:- Mobile applications: Immediate feedback while processing happens in background
- Web applications: Non-blocking user interfaces with real-time updates
- High-volume scenarios: Process multiple images concurrently
- User-facing tools: Food logging apps, dietary tracking applications