REST APIs

Webhooks

Smarter AI Service delivers notifications over Webhook for 3rd party system integration.

How to use Smarter AI Webhooks

  • Smarter AI Cloud allows a client to register HTTP endpoints to receive data over POST requests to the registered URL.
  • The Smarter AI Webhook system allows a client to register one or multiple HTTP endpoints for different topics.
  • Use the Topic list API to get the list of the available topics.
  • Register HTTP endpoint using Create Webhook API with required topics.
  • A client can update subscribed topics using the Topic Subscribe and Topic Unsubscribe APIs.
  • A client can remove a Webhook endpoints with Delete Webhook API.

Notification Details

Webhooks deliver various types of notifications.

Event Notifications

  • Event Notification
  • Event Media Upload Completion Notification

Historical Event Request Notifications

  • Historical Event Recording Request Status Change Notification

Recording Retrieval Request Notifications

  • Upcoming Media List Notification
  • Media File Upload Notification
  • Device Offline Notification for Recording Retrieval
  • Device Parking Mode Notification for Recording Retrieval

Device State-Related Notifications

  • Device Onboarded Notification
  • Parking Mode Status Changed Notification
  • Device Presence Status Changed Notification
  • Device Firmware Updated Notification

Trip Notifications

  • Trip Start Notification
  • Trip End Notification

External Device-Related Notifications

  • External Device Plugged Notification (Pairing)
  • External Device Unplugged Notification (Unpairing)

Health Tag Notifications

  • Notification for Device Health Tag Assign
  • Notification for Device Health Tag Unassign

Topics and sample notification

The notification will be dispatched to the Webhook URL specified by the consumer.

Smarter AI Cloud will send multiple topics to the same Webhook URL.

uuid, timestamp, topic, and data are common for all new Webhook POST requests.

  • uuid - Unique ID of this particular notification.
  • timestamp - Timestamp of Webhook notification dispatched.
  • topic - The topic of the notification. This topic varies for each type of notification.
  • data - Contains the data associated with a push notification


Event Notifications

Event Notification -topic.event.triggered

Smarter AI will trigger this Webhook Notification once an Event is registered in the Cloud. At the moment of reporting, the media (Video, Audio, AI Inferencing Data, Sensor, and CAN Bus data) won't be available on the cloud and will be patched gradually. To retrieve the media, subscribe to #event-media-upload-completion-notification.

Sample notification

{
  "uuid": "3d9b0153-901c-1656-0729-8b68284f5b23",
  "timestamp": 1649842374973,
  "topic": "topic.event.triggered",
  "data": {
    "id": "719967230113516",
    "tenantId": "1",
    "endpointId": 4506,
    "deviceId": "CA20440068",
    "timestamp": 1649833521479,
    "sources": [
      "353e8afc-dacb-42a5-8e82-0647cf13f513"
    ],
    "triggerId": "edd3ecf2-b78d-4fbd-a9e4-6dae4a3ef80d",
    "triggerName": "# No Driver (60s)",
    "deviceLabel": "Bhadra AI Dashcam - CA20440068",
    "userInitiatedEventRequestId": "c1994e88-1f0d-4132-b913-093585938f6f",
    "triggerCategoryName": "Driver.Authenticated"
  }
}

Note- userInitiatedEventRequestId filed is optionally populated with the request ID when the Event is generated by Historical Event API.


Event Media Upload Completion Notification - topic.event.data.uploaded

The event media is uploaded asynchronously and combined with event information. Once all media is uploaded, this webhook notification is sent.

Sample notification

{
  "uuid": "3d9b0153-901c-1656-0729-8b68284f5b23",
  "timestamp": 1649842374973,
  "topic": "topic.event.data.uploaded",
  "data": {
    "id": "719967230113516",
    "tenantId": "1",
    "endpointId": 4506,
    "deviceId": "CA20440068",
    "timestamp": 1671457659578,
    "endTimestamp": 1671457689578,
    "recordingStartTimestamp": 1697663529460,
    "recordingEndTimestamp": 1697663543133,
    "sources": [
      "353e8afc-dacb-42a5-8e82-0647cf13f513"
    ],
    "triggerId": "edd3ecf2-b78d-4fbd-a9e4-6dae4a3ef80d",
    "triggerName": "# No Driver (60s)",
    "deviceLabel": "SAI Dashcam - CA20440068",
    "triggerCategoryName": "Driver.Authenticated",
    "recordings": [
      {
        "startTimestamp": 1649833503811,
        "endTimestamp": 1649833564233,
        "source": "vid_2",
        "type": "VIDEO",
        "url": "https://accind0ds1.blob.core.windows.net/eventrecording2/dir/36e7f87c-1590-441a-b125-8942f32dfb171649833565229.mp4?sig=vQL6qY7LyqsPCFt%2FOYctzHzTzl%2FuJmxV1Wa4Ja85ehY%3D&se=2022-04-13T10%3A32%3A41Z&sv=2015-12-11&sp=rcw&sr=b"
      },
      {
        "startTimestamp": 1649833507844,
        "endTimestamp": 1649833568253,
        "source": "vid_1",
        "type": "VIDEO",
        "url": "https://accind0ds1.blob.core.windows.net/eventrecording4/dir/c29b90a5-919b-4d0e-b70d-99906697118a1649833569655.mp4?sig=TOHGKFisdPGwfOXawMbcXseZbq6KC%2Fo2KBijdlaNnQY%3D&se=2022-04-13T10%3A32%3A41Z&sv=2015-12-11&sp=rcw&sr=b"
      },
      {
        "startTimestamp": 1649833517337,
        "endTimestamp": 1649833577278,
        "source": "vid_2",
        "type": "B_BOX",
        "url": "https://accind0ds1.blob.core.windows.net/eventrecording0/dir/ec485bb0-d6c5-4b16-a64d-c9281e570e451649833578863.json?sig=Ak4lB1iQULSyL6YhleCj6A5hBz49jjA5WhFHGFRCpcM%3D&se=2022-04-13T10%3A32%3A41Z&sv=2015-12-11&sp=rcw&sr=b"
      }
    ]
  }
}

Historical Event Request Notifications

Historical Event Recording Request Status Change Notification - topic.recording.request.status

Smarter AI Cloud will alert clients to any changes in a Historical Event Recording Request status.

The possible Statuses are: SENT, ONGOING, COMPLETED, FAIL

For the FAIL status, the reason is stored in the failureReason field within the response body.

Sample notification

{ 
   "uuid": "2dcb66ba-ff70-93e6-8f66-ac9ea28df949", 
   "timestamp": 1694005803439,
   "topic": "topic.recording.request.status", 
   "data": {
    "requestId": "11a0512e-61ad-4937-b270-e02ca5fae9be",
    "endpointId": 123251,
    "status": "COMPLETED",
    "summary": "",
    "failureReason": "",
    "startTime": 1699619462333,
    "length": 5,
    "content": "ALL"
   }
}

Recording Retrieval Request Notifications

Upcoming Media List Notification - topic.recording.upcoming

When a recording is requested from the Device, a list of the media to be uploaded for that specific request is sent over this webhook topic.

Sample notification for a successful request: 

{
  "uuid": "9049f8fe-7171-d4fe-9db4-a9d8577b5aae",
  "timestamp": 1654005766628,
  "topic": "topic.recording.upcoming",
  "data": {
    "requestId": "c19b79ef-f1da-4c68-b1cd-bd5f0e52ed05",
    "status":"AVAILABLE",
    "timeout": 0,
    "upcomingMediaList": [
      {
        "source": "vid_1",
        "type": "VIDEO",
        "startTime": 1654005032141,
        "endTime": 1654005094067,
        "available": true
      },
      {
        "source": "vid_2",
        "type": "VIDEO",
        "startTime": 1654005039857,
        "endTime": 1654005101786,
        "available": true
      },
      {
        "source": "vid_1",
        "type": "VIDEO",
        "startTime": 1654005094131,
        "endTime": 1654005154069,
        "available": true
      },
      {
        "source": "vid_2",
        "type": "VIDEO",
        "startTime": 1654005101853,
        "endTime": 1654005161798,
        "available": true
      },
      {
        "source": "vid_1",
        "type": "VIDEO",
        "startTime": 1654005154144,
        "endTime": 1654005214070,
        "available": true
      },
      {
        "source": "vid_2",
        "type": "VIDEO",
        "startTime": 1654005161855,
        "endTime": 1654005221785,
        "available": true
      }
    ]
  },
  "status": "AVAILABLE",
  "endpointId" 12345
}

The Device can report an empty media file list in a few cases:

  • AVAILABLE - All requested files have already been uploaded to the cloud.
  • NO_DATA - No files are available on the device.
  • BUSY - The camera is busy with other requests. The client can retry after the specified timeout milliseconds.
  • MEDIA_NOT_READY - Files are not completely captured yet. The client should retry later

Sample notification for a failed request:

{
  "uuid": "9049f8fe-7171-d4fe-9db4-a9d8577b5aae",
  "timestamp": 1654005766628,
  "topic": "topic.recording.upcoming",
  "data": {
    "requestId": "c19b79ef-f1da-4c68-b1cd-bd5f0e52ed05",
    "status": "BUSY",
    "timeout": 300000,
    "upcomingMediaList": []
  }
}

Media File Upload Notification - topic.recording.response

When the Device completes uploading media from the local storage, our system will deliver the details of the newly uploaded media to the caller via Webhook.

Sample notification

{
  "uuid": "25fb4c7c-6e7e-8854-0f6c-d2cfce0a82e9",
  "timestamp": 1654005797450,
  "topic": "topic.recording.response",
  "data": {
    "requestId": "c19b79ef-f1da-4c68-b1cd-bd5f0e52ed05",
    "source": "vid_2",
    "type": "VIDEO",
    "available": true,
    "startTime": 1654005161855,
    "endTime": 1654005221785,
    "downloadUrl": "https://accind0ds1.blob.core.windows.net/eventrecording0/dir/e62b224b-2b34-4e9a-b673-c8eeb38459281654005783408.mp4?sig=xJZv830ZKR%2FGAgjXWUHKkK3pqzj6%2FRJeIbbPen%2FPZvg%3D&se=2022-05-31T15%3A03%3A17Z&sv=2015-12-11&sp=rcw&sr=b",
    "downloadUrlExpiry": 1654009396450
  }
}

Device Offline Notification for Recording Retrieval - topic.recording.camera.offline

Smarter AI Cloud will notify you when you request a Historical Event Recording for an offline Device.

Sample notification

{
  "uuid": "25fb4c7c-6e7e-8854-0f6c-d2cfce0a82e9",
  "timestamp": 1654005797450,
  "topic": "topic.recording.camera.offline",
  "data": {
    "requestId": "c19b79ef-f1da-4c68-b1cd-bd5f0e52ed05",
    "startTime": 1654005161855,
    "endTime": 1654005221785,
    "endpointId": 1234,
    "message": "Recordings will be retrieved from the camera once the camera comes online."
  }
}

Device Parking Mode Notification for Recording Retrieval - topic.recording.camera.inparking

Smarter AI Cloud will notify you when you request a Historical Event Recording for a Device in parking mode. Our Cloud service sends a wake-up signal to the Device to retrieve the recordings.

Sample notification

{
  "uuid": "25fb4c7c-6e7e-8854-0f6c-d2cfce0a82e9",
  "timestamp": 1654005797450,
  "topic": "topic.recording.camera.inparking",
  "data": {
    "requestId": "c19b79ef-f1da-4c68-b1cd-bd5f0e52ed05",
    "startTime": 1654005161855,
    "endTime": 1654005221785,
    "endpointId": 1234,
    "message": "Recordings will be retrieved from the camera once the camera wakes up from parking."
  }
}

Device State-Related Notifications

Notification for Device Onboard - topic.device.onboarded

Smarter AI Cloud sends this notification when a new Device is onboarded.

{ 
   "uuid": "2dcb66ba-ff70-93e6-8f66-ac9ea28df949", 
   "timestamp": 1694005803439,
   "topic": "topic.device.onboarded", 
   "data": {   
     "tenantId": "X",  
     "deviceSerialNumber": "XYZ",  
     "endpointId": 0,   
     "timestamp": 1694005803432  
   }
}

Notification for Parking Mode Status - topic.device.parking

Smarter AI Cloud sends this notification when the Device changes the parking mode.

Sample notification

{
  "uuid": "75fe9a2f-4096-5524-6d97-52c913399484",
  "timestamp": 1714648647153,
  "topic": "topic.device.parking",
  "data": {
    "endpointId": 123043,
    "deviceId": "CA20440068",
    "tenantId": "98ed2e00-2390-4786-a49d-6e9d2d72d3e2",
    "timestamp": 1714639417112,
    "status": "NotInParkingMode"
  }
}

The possible status are:

  • InParkingMode
  • NotInParkingMode
  • GoingToParkingMode

Notification for Device Presence Status - topic.device.presence

Smarter AI Cloud sends this notification when the Device changes its presence status.

Sample notification

{
  "uuid": "2991ee8d-ec42-ebce-317d-535c13834870",
  "timestamp": 1714655535566,
  "topic": "topic.device.presence",
  "data": {
    "endpointId": 122723,
    "deviceSerialNumber": "F402245XYRXTK",
    "tenantId": "1",
    "deviceOnline": true,
    "lastOnlineTime": 1714648124000
  }
}

The possible deviceOnline values are

  • true - Indicates Device Online
  • false - Indicates Device Offline

Device Firmware Updated Notification - topic.device.firmware.updated

Smarter AI Cloud sends this Webhook notification when a Device completes a Firmware update

Sample notification

{
  "uuid": "2991ee8d-ec42-ebce-317d-535c13834870",
  "timestamp": 1722511386680,
  "topic": "topic.device.firmware.updated",
  "data": {
    "deviceSerialNumber":"F402245XYRXTK",
    "timestamp":1722511386680,
    "firmwareType":"APPLICATION_PACKAGE",
    "previousVersion":"2022.24.07",
    "updatedVersion":"2024.20.17-local"
  }
}

The Webhook notification can have the following firmwareTypes

  • APPLICATION_PACKAGE - The Smarter AI Camera Firmware
  • CAN_BUS_FW - CAN Bus Firmware on the MCU connected with CAN
  • LTE_MODEM_FW - LTE modem Firmware
  • OEM_IMAGE - Customized OS patch for Smarter AI Camera
  • SMART_CABLE_FW - Smarter Cable CAN Firmware
  • SYSTEM_IMAGE - Operating System
  • SUPPORTING_APPLICATION - 3rd party application, running on the Camera

Trip Notifications

Trip Start Notification - topic.trip.started

Smarter AI Cloud sends this notification when a Trip is started.

Sample notification

{
  "uuid": "1a3071d5-2557-51c2-a82d-b6f6a813dc7e",
  "timestamp": 1691586099994,
  "topic": "topic.trip.started",
  "data": {
    "tenantId": "X",
    "tripId": "397f92d4-4734-4c40-83c1-3dasd4c",
    "endpointId": 0,
    "geo": {
      "lon": 11.22,
      "lat": 22.33
    },
    "timestamp": 0,
    "isShortTrip": false
  }
}

Trip End Notification - topic.trip.ended

Smarter AI Cloud sends this notification when a Trip is completed.

Sample notification

{
  "uuid": "2bf45a75-4116-6234-36ad-f0cf65bd0169",
  "timestamp": 1691586152509,
  "topic": "topic.trip.ended",
  "data": {
    "tenantId": "X",
    "tripId": "397f92d4-4734-4c40-83c1-30asdasd074c",
    "endpointId": 0,
    "geo": {
      "lon": 11.22,
      "lat": 22.33
    },
    "timestamp": 0,
    "isShortTrip": false
  }
}

External Device-Related Notifications

Notification for Plugged Device (Pair) - topic.device.plugged.paired

Smarter AI Cloud sends this webhook notification when an external device is paired.

Sample notification

{
  "uuid": "c855b43b-74b1-8b4f-17a0-31b75030ba40",
  "timestamp": 1693379323943,
  "topic": "topic.device.plugged.paired",
  "data": {
    "tenantId": "X",
    "endpointId": 0,
    "pluggedDevice": "XYZ",
    "timestamp": 1693379321884
  }
}

Notification for Unplugged Device (Unpair) - topic.device.plugged.unpaired

Smarter AI Cloud sends this webhook notification when an external device is unpaired.

Sample notification

{
  "uuid": "c855b43b-74b1-8b4f-17a0-31b75030ba40",
  "timestamp": 1693379323943,
  "topic": "topic.device.plugged.unpaired",
  "data": {
    "tenantId": "X",
    "endpointId": 0,
    "unpluggedDevice": "XYZ",
    "timestamp": 1693379321884
  }
}

Health Tag Notifications

Notification for Device Health Tag Assign - topic.device.health.tag.assign

Smarter AI Cloud sends this webhook notification when a health tag is assigned to a device.

Sample notification

{ 
   "uuid": "2dcb66ba-ff70-93e6-8f66-ac9ea28df949", 
   "timestamp": 1694005803439,
   "topic": "topic.device.health.tag.assign", 
   "data":{  
      "healthTag": "GO.Error.IOX",  
      "endpointId": 123,  
      "comment": "",  
      "timestamp": 1698692782259,  
   }
}

Notification for Device Health Tag Unassign - topic.device.health.tag.unassign

Smarter AI Cloud sends this webhook notification when a health tag is removed from a device.

Sample notification

{ 
   "uuid": "2dcb66ba-ff70-93e6-8f66-ac9ea28df949", 
   "timestamp": 1694005803439,
   "topic": "topic.device.health.tag.unassign", 
   "data":{  
      "healthTag": "GO.Error.IOX",  
      "endpointId": 123,  
      "comment": "",  
      "timestamp": 1698692782259,  
   }
}