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

note

Only the On-premises version supports 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

warning

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