API Help Resources

Netradyne Data Sharing Model

• Introduction
• Rest API
• Live tracking data using AWS S3 to S3 replication

• Webhooks

  Webhooks

  Introduction to Webhooks

  Webhooks enable users to subscribe to data from Netradyne. In this case, Netradyne pushes data as and when the event occurs or at a pre-defined frequency. For example, events such as Alerts (Traffic Light Violation) may be pushed when the event occurs, whereas Inertial Measurement Unit (IMU) data such as Gyrometer readings will be pushed at a pre-defined frequency because the vehicles constantly generate this data during the drive. 

  Webhooks are available for the events described in the following table. When one of the below events is triggered, an HTTPS POST payload is sent to the Webhook's configured URL. All the below Webhooks also support multiple subscriptions. For example, consider the case of the alert Webhook. A client may want to:

  • Push “Potential Collision” alerts to an insurance company.
  • Push High-G alerts of subtype “Rough Road” to a public Department of Transportation.
  • Push any alert configured by the client to an e-learning company.

  In this scenario, the client can have multiple subscriptions to the alert Webhook.

  The configurations can be set up in the Netradyne system based on URLs provided by the user.

  Event	Description
  alert	Alert event detected.
  distilledObsData	Observation data such as GPS, Accelerometer, Gyrometer, etc., that are reported by the Driver•i device.
  driverAssignment	Drive Time assigned to the Driver.
  entityChange	Notify changes in the properties of an entity. This event is currently supported for the Vehicle entity.

   
  Careful consideration and subscription to events will limit the number of HTTP requests made to the server. The list of subscribed events can be changed through the API. API information is available at https://resources.netradyne.com/ . 

  Prerequisites

  Ensure that the following requirements are met before receiving data through Webhooks: 

  • The Webhooks API uses the HTTPS protocol. Users who want to receive data through Webhooks must set up an HTTPS server. This is the Webhooks URL configured in the Netradyne system, where the data will be posted. All endpoints accept and return JSON.
  • Netradyne creates a unique Tenant name for each user. Users must contact Netradyne Support to know their unique Tenant name. 

  Order of Events

  Netradyne does not guarantee delivery of events in the order in which they were generated.

  Specifications for Registered POST API Handler

  Return a 2xx HTTP status code

  To acknowledge receipt of an event, the client’s endpoint must return a 2XX HTTP status code to Netradyne server.

  All response codes outside this range, including 3xx codes, indicates that the client did not receive the event. If Netradyne server does not receive a 2XX HTTP status code, the post data attempt is repeated twelve times for a total duration of 90 minutes, as follows:

  • 0th min (time of event) : 3 retry attempts
  • 15th min: 3 retry attempts
  • 45th min: 3 retry attempts
  • 90th min: 3 retry attempts

  Security

  The following practices are recommended:

  • Receive events with an HTTPS server.
  • Netradyne supports signing of Webhook requests based on a shared secret between Netradyne and its users using HMAC-based authentication. Users can verify that requests are generated by Netradyne and can protect against spoofing.

  Check the Webhooks Signature

  Netradyne can sign the Webhook events that it sends to client endpoints by including a signature in each event's Netradyne-Signature header. This allows users to verify that the events were sent by Netradyne and not by a third party. Users can verify signatures by using their own solution based on the algorithm mentioned here. 

  Preventing Replay Attacks

  A replay attack occurs when an attacker intercepts a valid payload and its signature, and then re-transmits them. To mitigate such attacks, Netradyne includes a timestamp in the "Netradyne-Signature" header. Because this timestamp is part of the signed payload, it is also verified by the signature so an attacker cannot change the timestamp without invalidating the signature. If the signature is valid but the timestamp is too old, you can have your application reject the payload. Netradyne generates the timestamp and signature each time an event is sent to your endpoint. If Netradyne retries an event (for example, your endpoint previously replied with a non-2xx status code), then a new signature and date are generated for the new delivery attempt.

  Example:
  Netradyne-Signature: 

  

  Extract the timestamp and signatures from the Netradyne-Signature header:
  Split the header using character as separator to get a list of elements. Then split each element using the = character as the separator to get a prefix and value pair. The value for the prefix timestamp corresponds to the timestamp and hmac corresponds to the signature.

  Netradyne's Algorithm 
  Step1: Prepare the signed_payload string.
  
  

  Step2: Use the HMAC algorithm to create a signature based on a shared secret.
  
  

  Step3: After calculating the HMAC value, it must be sent to the server. This is done by providing a custom header.
  

  Step 4: Compare the signatures.
  Verify the events that Netradyne sends to your Webhook endpoints.

   

  Alert Webhook

  Alerts are driving events captured by Driver•i® device. The application generates real-time Alerts to ensure visibility of the driving behavior and incidents that need quick action. This helps monitor performance, and proactively address any incidents caused and prevent them from happening in the future. 

  The alert webhook pushes the latest data when an Alert is generated and updated data for the following events:   

  Changes to Alert Status  

  • When the Alert status is changed from the previous status 
  • When the Alert is rejected by the user 
  • When the Alert is converted to a DriverStar. The newly created DriverStar will be posted and the old Alert will be replaced with updated data. 

  Changes to Video Status 

  • When a new video is available (full or trimmed)  
  • When the video gets annotated 
  • When the video is deleted on the device 

  Updates to Driver Assignment 

  • When the driver data changes during a driver assignment update.
  • When the alert assigned to a driver previously was changed during the driver assignment update. In this case, the alert webhook pushes the details with new driver data as an alert update and replaces the old alert with updated data.

  The following table describes the parameters for the Alert event: 

  Parameter	Description
  duration	The duration of the alert.
  gpsData	Indicates the GPS coordinates:  latitude: Latitude of the position in decimal degrees  longitude: Longitude of the position in decimal degrees   timestamp: Time when the event was captured
  tenantName	The unique name of the Fleet.
  driver	Information about the driver. Includes the following:  firstName: First name of the driver  lastName: Last name of the driver  driverId:  Unique ID assigned to each driver
  details	Alert information. Includes the following:  Parameter  Description  Possible Values  severity  The risk level associated with an Alert  1, 2, 3, 4  severityDescription is also sent in the payload, which describes these levels.   severityDescription  Description of the Alert severity 1: ALERT (SEVERE) 2: WARN (MODERATE) 3: DRIVER-STAR  4: NEUTRAL  cause  The reason for the Alert  0: Driver  1: Third Party  2: Undetermined   typeId  Type of Alert  A value from 0 through 25.  typeDescription  Description of the Alert Type  0: Neutral Events  1: Following Distance  2: Hard Braking  3: Hard Acceleration  4: High-G  5: Traffic light violation  6: Hard turn  7: Relative speeding  8: Sign violations  9: Speeding violations  10: Seatbelt compliance  11: Driver-initiated  12: Collision warning  13: Weaving  14: U-turn  15: Error events  16: Driver drowsiness  17: DriverStar  18: Railroad crossing  19: Driver distraction  20: Swerve  21: Camera obstruction  22: No trucks sign violations  23: Face mask compliance  24: Requested Video  25: Low impact  alertVideoStatus  Status of alert video    subTypeDescription  Description of the Alert’s subtype. For example, for Driver Distraction, the subtypes can be “Talking on phone”, “Looking at phone”, “Looking down”, etc.    category Category of Alert A value of 1 or 3. categoryDescription  Description of Alert Category. For example:  Beta Alert – A new alert that is under evaluation and can be used for coaching, but it will not impact GreenZone score  Regular Alert – GA alerts  1: Regular alert   3: Beta alert  confidence Indicates the confidence score of the generated Alert    A value from 0.0 to 1.0
  videos	Video information. Includes the following:  Parameter  Description  Possible Values  id  Unique video identifier    position  Camera position  Note: The external cameras (positions 4,5,6, and 7) are available when fleet has bought Driver•i Hubx.  0: outward  1: inward  2: left  3: right  4: external 0  5: external 1  6: external 2  7: external 3  status  video status  -1: Video not available  0: Video can be requested  1: Video pending  2: Video available    timestamp  Time when the event was captured
  id	Unique Alert identifier
  timestamp	Time when the alert was generated.
  updatedOn	Time when the Alert was updated  (This is a new parameter. It is supported from  January 2021.
  status	Status of the Alert. Possible values are:  Confirmed  Rejected  (This is a new parameter supported for changes to any of the Alert properties. It is supported from January 2021).
  vehicle	Vehicle information. Includes the following:  vehicleNumber: Unique vehicle number in the fleet  vin: Vehicle Identification Number
  webhookType	The event corresponding to the webhook, in this case “alert”.
  camera	Camera information. Includes the following:  id: Unique camera identifier.

  This is the Webhook sample payload to share the Alert event detected.

  { 
  
      "gpsData": [{ 
  
              "latitude": 38.258686, 
  
              "timestamp": 1608503046840, 
  
              "longitude": -85.72605 
  
          }, 
         { 
  
              "latitude": 38.258686, 
  
              "timestamp": 1608503046840, 
  
              "longitude": -85.72605 
  
          } 
  
      ], 
  
      "videos": [{ 
  
              "id": 13107312725, 
  
              "position": 1, 
  
              "status": 1, 
  
              "timestamp": 1608502989597 
  
          }, 
           { 
  
              "id": 13107312726, 
  
              "position": 2, 
  
              "status": 1, 
  
              "timestamp": 1608502989597 
  
          }, 
          { 
  
              "id": 13107312727, 
  
              "position": 3, 
  
              "status": 1, 
  
              "timestamp": 1608502989597 
  
          }, 
          { 
  
              "id": 13107312728, 
  
              "position": 4, 
  
              "status": 1, 
  
              "timestamp": 1608502989597 
  
          }, 
          { 
  
              "id": 13107312729, 
  
              "position": 5, 
  
              "status": 1, 
  
              "timestamp": 1608502989597 
  
          }, 
          { 
  
              "id": 13107312730, 
  
              "position": 6, 
  
              "status": 1, 
  
              "timestamp": 1608502989597 
  
          }, 
           { 
  
              "id": 13107312731, 
  
              "position": 7, 
  
              "status": 1, 
  
              "timestamp": 1608502989597 
  
          }, 
           { 
  
              "id": 13107312724, 
  
              "position": 0, 
  
              "status": 2, 
  
              "timestamp": 1608502989597 
  
          } 
  
      ], 
  
      "updatedOn": 1608503341540, 
  
      "vehicle": { 
  
          "vehicleNumber": "xxxxxx", 
  
          "vin": " xxxxxx" 
  
      }, 
  
      "webhookType": "alert", 
  
      "duration": 1, 
  
      "tenantName": "xxxxxx", 
  
      "driver": { 
  
          "firstName": "xxxxxx", 
  
          "lastName": "xxxxxx", 
  
          "driverId": "xxxxxx" 
  
      }, 
  
      "details": { 
  
          "severity": 2, 
  
          "confidence": null, 
  
          "cause": 2, 
  
          "typeId": 4, 
  
          "typeDescription": "HIGH-G", 
  
          "alertVideoStatus": 2, 
  
          "severityDescription": "WARN", 
  
          "category": 1, 
  
          "subTypeDescription": "Moderate Impact", 
  
          "categoryDescription": "Regular Alert" 
  
      }, 
  
      "id": 43, 
  
      "camera": { 
  
          "id": "1630019XXXX" 
  
      }, 
  
      "timestamp": 1608503046840, 
  
      "status": "CONFIRMED" 
  
  } 

  entityChange Webhook

  The entityChange webhook can be used to notify changes in the properties of an entity. In the current implementation, the webhook is invoked when a vehicle’s properties (VIN, License Plate Number, and Vehicle Number) are changed. The webhook can be used in future to notify change events for other entities.  

  The following table describes the parameters for the entityChange event. 

  Parameter	Description
  tenantName	The unique name of the Fleet.
  propertiesChanged	Contains the name, old value, and new value of the properties that have changed. Property Description  name Name of the property that has changed. Possible values are vin, licencePlateNumber, and vehicleNumber.  newValue  New value of the property.  currentValue  Existing value of the property.
  updatedOn	Time when the entity property was updated.
  entity	The entity whose property changed.
  webhookType	The event corresponding to the webhook, in this case “entityChanged”

  The following are the Webhook sample payloads for the entityChange event.  

   

  Scenario 1: One property changed 

  { 
  
    "tenantName": "N371818071473182", 
  
    "propertiesChanged": [ 
  
      { 
  
        "name": "vehicleNumber", 
  
        "newValue": "VehNum15", 
  
        "currentValue": " VehNum19" 
  
      } 
  
    ], 
  
    "updatedOn": 1612380493492, 
  
    "entity": "vehicle", 
  
    "webhookType": "entityChange" 
  
  } 

   

  Scenario 2: Two properties changed

  { 
  
    "tenantName": "N371818071473182", 
  
    "propertiesChanged": [ 
  
      { 
  
        "name": "vin", 
  
        "newValue": "WBXPC93487WF32148", 
  
         "currentValue":  5NPEB4AC2BH235831" 
  
      }, 
  
      { 
  
       "name": "licensePlateNumber", 
  
        "newValue": "ABC 12345", 
  
        "currentValue": "XYZ 123409" 
  
      } 
  
    ], 
  
    "updatedOn": 1612380550376, 
  
    "entity": "vehicle", 
  
    "webhookType": "entityChange" 
  
  } 

   

  Scenario 3: Three properties changed 

  { 
  
    "tenantName": "N371818071473182", 
  
    "propertiesChanged": [ 
  
      { 
  
        "name": "vin", 
  
        "newValue": "1G2HY52K134158002", 
  
         "currentValue":  2D4GV58265H121057" 
  
      }, 
  
      { 
  
        "name": "licensePlateNumber", 
  
        "newValue": "MNO 12345", 
  
        "currentValue": "KLM 123409" 
  
      }, 
  
      { 
  
        "name": "vehicleNumber", 
  
        "newValue": "VehNum 20", 
  
        "currentValue": " VehNum 35" 
  
      } 
  
    ], 
  
    "updatedOn": 1612380572983, 
  
    "entity": "vehicle", 
  
    "webhookType": "entityChange" 
  
  } 

   

  distilledObsData Webhook

  The Driver•i device collects information related to geolocation, accelerometer and gyrometer readings, vehicle speed, etc., and uploads it to Netradyne Cloud for every 10 minutes of drive time. The distilledObsData webhook pushes a subset of this observation data to users who have subscribed to receive data through webhooks.  

  
  However, users do not receive this data in real time. If the LTE connectivity is poor, there can be a delay in uploading the data-heavy observation data file. In some cases, it might take around 20 minutes or more to push the data to the users. 

   

  The following table describes the parameters for the distilledObsData event.  

  Parameter	Description
  deviceModes	Captures the following states of the device:  State  Description  Possible Values  Privacy Mode  Indicates whether privacy was enabled or not during the session in which this file was recorded  0: Privacy was not enabled  1: Privacy was enabled (inward camera video is not captured)  idle  Indicates engine idle status during the session in which this file was recorded  0: Vehicle was not idle (vehicle was not at zero speed for a specified time (300 seconds))  1: Vehicle was idle (video files are not stored in internal storage.)  ignition_status  Indicates the status of ignition line during the session in which this file was recorded  0: Ignition was OFF during the entire session  1: Ignition was ON at some point during the session
  tenantName	Unique name of the Fleet.
  geoLocation	Geographic location of the device. Includes the following:  altitude: Altitude of the device in meters, relative to sea level  bearing: Direction in degrees  accuracy: Accuracy, with a 95% confidence level, of the latitude and longitude properties expressed in meters  long: Longitude of the position in decimal degrees. A value of 181 indicates that the value is invalid.  lat: Latitude of the position in decimal degrees. A value of 91 indicates that the value is invalid.  speed: Speed of the device in miles per hour  timestamp: Time when the event was captured
  accelerometer	Accelerometer in X, Y and Z directions   accZ: Indicates driving/longitudinal direction and forward is positive  accY: Indicates lateral direction and right is positive  accX: Indicates gravity direction and is positive downwards  timestamp: Time when the event was captured
  gpsStartTime	Start time of the current minute captured from GPS sensor
  gyrometer	gyroX: Rotational force around yaw  gyroY: Rotational force around pitch  gyroZ: Rotational force around roll  timestamp: Time when the event was captured (Epoch time)
  gpsEndTime	End time of the current minute captured from GPS sensor
  vehicle	Vehicle information. Includes the following:  vehicleNumber: Unique vehicle number within the fleet  vin: Vehicle Identification Number
  camera	Includes the following: id: Unique camera identifier
  webhookType	The event corresponding to the Webhook, in this case “distilledObsData”.

  This is a Webhook sample payload to share observation data, such as GPS, accelerometer, gyrometer, etc., reported by the Driver•i device. 

  {
  "tenantName": "XXXXXXXX",
  "deviceModes": {
  "idle": 0,
  "ignition_status": 1,
  "privacymode": 1
  },
  "geoLocation": [
  {
  "altitude": 706.1,
  "bearing": 150,
  "accuracy": 3.54,
  "long": -114.9109421,
  "lat": 35.9719658,
  "speed": 0,
  "timestamp": 1573791742000
  }
  ],
  "accelerometer": [
  {
  "accZ": -0.629675,
  "accY": -0.687136,
  "accX": 9.87848,
  "timestamp": 1573791740126
  }
  ],
  "gpsStartTime": 1573791742000,
  "gyrometer": [
  {
  "gyroX": 0.824427,
  "gyroY": -1.03817,
  "gyroZ": -4.85496,
  "timestamp": 1573791740126
  }
  ],
  "gpsEndTime": 1573791801000,
  "vehicle": {
  "vehicleNumber": "XXXXXX",
  "vin": "XXXXXXXX"
  },
  "camera":
  {
  "id": "string"
  },
  "webhookType": "distilledObsData"
  }