Webhooks & API Response

This guide covers the API response format and webhook configuration for USDOT OCR.

---

API Response Format

Both direct API calls and webhook notifications use the same JSON response format:

{
  "original_width": 280,
  "original_height": 280,
  "results": [
    {
      "texts": [
        {
          "value": "USDOT0557341Z",
          "score": 0.99888915
        }
      ],
      "object": {
        "score": 0.7782135009765625,
        "label": "usdot",
        "value": {
          "xmin": 0.2525801956653595,
          "xmax": 0.7522493004798889,
          "ymin": 0.3767074644565582,
          "ymax": 0.49078893661499023
        }
      }
    }
  ],
  "processing_time": 2110.444,
  "timestamp": "2025-09-13T17:35:56.030478+00:00"
}

Response Fields

Field	Description
original_width	Width of the original image in pixels
original_height	Height of the original image in pixels
results	List of detected USDOT readings, sorted by confidence score (descending)
processing_time	Processing time in milliseconds
timestamp	ISO timestamp of when the request was processed

Results Object

Each item in the results array contains:

texts Array:

• value: The detected USDOT number as text
• score: Confidence score (0.0 to 1.0) for the text recognition

Response Scenarios

Successful Detection:

• results array contains one or more detection objects
• Each detection includes confidence scores and bounding box coordinates

No Detection:

• results array will be empty: "results": []
• This still represents a valid API response

---

Webhooks Configuration

Both On-Premise and Cloud versions support webhooks for real-time notifications when USDOT processing is complete.

Setup

1. Go to Webhooks settings page
2. Add your target URL
3. Configure webhook parameters

Requirements

Target URL Requirements:

• Must return HTTP status code 200
• Should handle JSON POST requests
• Must be publicly accessible

⚠️ Important: If your target URL consistently returns error codes, the webhook will be automatically removed and the account owner will be notified by email.

Webhook Delivery

Content Type: application/json

Delivery: A webhook is sent for every API call, even when no USDOT information is detected.

Data Format: Same as the API response format shown above.

Testing Webhooks

For quick testing and development:

1. Use webhook.site to generate a test URL
2. Configure this URL in your webhook settings
3. Make API calls and view the webhook data in real-time
4. Use this to verify your webhook payload structure

---

Best Practices

Confidence Scores

• Use the score values to filter results based on your accuracy requirements
• Higher scores indicate more reliable detections
• Consider both text and object detection scores for validation

Error Handling

• Always check if the results array is empty
• Implement retry logic for webhook endpoints
• Log webhook deliveries for debugging