OTR Business Events API External - Version (9/29/2025)

Overview

The OTR Business Event API ingests over-the-road (OTR) business events produced by vendors and internal systems. Clients submit a typed payload (OTRBusinessEventInput) describing the event, including device/asset context, event category/type, measured values, a geolocation point, and a short time-series of supporting datapoints.

• Operation surface (from model): OTRBusinessEvent (single operation)
• Payload: JSON
• Response: Success returns 200 OK with no body (void). Validation errors return InvalidInputException (400).
• (Implementation detail, not in model): The service typically deduplicates by eventId.

Authentication & Access

• Auth: AWS Signature Version 4 (SigV4).
• Authorization: Requests must originate from allow-listed AWS accounts (environment config). Non-allow-listed callers receive 403 Forbidden.

Protocol & Endpoint

• Protocol: HTTPS
• Content-Types: application/json
• Path (canonical REST mapping): POST → OTRBusinessEvent

(Your Gateway may route directly to the Lambda with an aws_proxy integration; the REST path above is the recommended public shape.)

Operation

Publish OTR Business Event

POST /OTRBusinessEvent

Submit a single OTR event.

Each environment has a separate URL

Headers

• Authorization: AWS4-HMAC-SHA256 ... (SigV4)
• Content-Type: application/json
• X-Request-Id (optional, recommended)

Request Body

OTRBusinessEventInput

Success Response

• 200 OK (empty body)

Error Responses

• 400 Bad Request — InvalidInputException (see Errors)
• 403 Forbidden — caller's AWS account not allow-listed
• 5xx — InternalServerException server/dependency errors

Onboarding & Testing Requirements

Gamma Testing Checklist:

• Verify SigV4 authentication works correctly
• Validate payload structure and required fields
• Test error handling for various scenarios (400, 403, 5xx responses)
• Confirm idempotency behavior with duplicate eventId values
• Validate geographic coordinates and data units
• Test with realistic data volumes and frequencies

Environment Progression:

• Gamma → Pre-production validation and testing
• Production → Live data submission only after successful Gamma validation

This approach ensures data quality and reduces the risk of production issues.

Schema

OTRBusinessEventInput

Required fields are marked ✱.

DataPoint

GeoPoint

AdditionalInformation

Enums

Examples

Full payload

{  
    "eventId": "d1c1b2f3-4455-4e4a-9f5a-111122223333",  
    "eventTimestamp": "2025-08-18T10:15:30Z",  
    "assetId": "V503768",  
    "assetType": "TRAILER",  
    "deviceId": "861836057633161",  
    "deviceManufacturer": "PHILLIPS",  
    "assetPart": "TIRE",  
    "eventCategory": "MAINTENANCE",  
    "eventType": "COLD_INFLATION_PRESSURE",  
    "currentValue": 72.0,  
    "triggerValue": 80.0,  
    "dataUnit": "PSI",  
    "triggerRule": "Event triggered when 3 datapoints crossed the 80 PSI threshold",
    "dataPoints": [  
        {"value": 78.0, "timeStamp": "2025-08-18T09:50:00Z", "dataUnit": "PSI"},  
        {"value": 75.5, "timeStamp": "2025-08-18T10:05:00Z", "dataUnit": "PSI"},  
        {"value": 72.0, "timeStamp": "2025-08-18T10:15:00Z", "dataUnit": "PSI"}  
    ],  
    "geoPoint": {"latitude": 33.4484, "longitude": -112.074},  
    "vendorName": "PCT",  
    "additionalInformation": {   
        "imageId": "img_20250818_101530_abc123",  
        "severity": "MINOR"  
    },  
    "version": 1  
}

Errors Catalog

Idempotency & Dedupe

(Behavioral; not explicitly encoded in the model)
Most deployments treat eventId as the idempotency key. Re-submitting the same payload with the same eventId will not create a second record; servers typically return 200 OK (ack) without side effects.

Notes for Implementers

• Timestamps: Use RFC 3339/ISO-8601 UTC strings (e.g., 2025-08-12T14:05:07Z).
• Units: Ensure dataUnit matches currentValue, triggerValue, and each dataPoints[*].dataUnit.
• Enums: Requests with unknown enum values will fail validation.
• Geo: latitude ∈ [-90, 90], longitude ∈ [-180, 180] (recommended validation).
• Access control: Keep your allow-list of AWS accounts in configuration/infra; return 403 otherwise.