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.

 
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: 

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. 

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.  

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"
}

driverAssignment Webhook

The following table describes the parameters for the driverAssignment event:

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

Scenario 1: Driver Recognized by the System 

{ 

  "tenantName": "N969870011344933", 

  "driver": { 

    "firstName": "Kenneth", 

    "lastName": "Grimes", 

    "driverId": "kennethg" 

  }, 

  "startTime": 1601534660839, 

  "endTime": 1601534720766, 

  "source": "VLS", 

  "webhookType": "driverAssignment", 

  "vehicle": { 

    "licensePlateNumber": "TN445078", 

    "vehicleNumber": "TN445078", 

    "vin": "VIN_TN445078" 

  }, 

  "netradyneDriverVehicleAssociationId": "6bc09cff-aee6-4956-a8c6-d5f785ad92a3" 

} 

Scenario 2: Drive Time Assigned to Driver by User in IDMS Dashboard 

{ 

  "tenantName": "N969870011344933", 

  "driver": { 

    "firstName": "Kenneth", 

    "driverId": "wueiwq353" 

  }, 

  "startTime": 1601172000000, 

  "endTime": 1601173800000, 

  "source": "USER", 

  "userName": "testUser", 

  "webhookType": "driverAssignment", 

  "vehicle": { 

    "licensePlateNumber": "bagh-001", 

    "vehicleNumber": "bagh-001", 

    "vin": "" 

  }, 

  "netradyneDriverVehicleAssociationId": "6bc09cff-aee6-4956-a8c6-d5f785ad92a3" 

} 

Scenario 3: Unknown Driver  

{ 

  "tenantName": "N969870011344933", 

  "driver": null, 

  "startTime": 1601386598801, 

  "endTime": 1601386658728, 

  "source": "BEACON", 

  "webhookType": "driverAssignment", 

  "vehicle": { 

    "licensePlateNumber": "TX903196", 

    "vehicleNumber": "TX903196", 

    "vin": "VIN_TX903196" 

  }, 

  "netradyneDriverVehicleAssociationId": "6bc09cff-aee6-4956-a8c6-d5f785ad92a3" 

} 

Scenario 4: Open Interval

{   

"tenantName": "N969870011344933",   

"driver": 

{     

"firstName": "Kenneth",    
 
"lastName": "Grimes",     

"driverId": "kennethg"   

},   

"startTime": 1601534660839,   

"endTime": 0,   

"source": "ELD",   

"webhookType": "driverAssignment",  
 
"vehicle": 

{     

"licensePlateNumber": "TN445078",    
 
"vehicleNumber": "TN445078",  
   
"vin": "VIN_TN445078"   

},   

"netradyneDriverVehicleAssociationId": "6bc09cff-aee6-4956-a8c6-d5f785ad92a3" }