Alert Notifications through WebHooks (Beta)

What are WebHooks?

WebHooks are a way that one application can send a message to another.
So when something happens in one app - it triggers a WebHook to send some data to another - and the other app can use this data and perform other actions if necessary.

TABLE OF CONTENTS


What are the applications/why would I use them?

In Telematics Guru - the way WebHooks are implemented is essentially a URL can be the recipient of an Alert Notification.
So when an alert is triggered in TG - some information is sent to that server in the form of a HTTP post.

This is useful when Telematics Guru is being used as the tracking platform - but a user has some other system which they need some of the telemetry data. There is no cost for this service, it is included in the TG asset fees. 

Examples:

  • An organisation uses TG for their asset tracking and driver behaviour monitoring. They also use a hiring or maintenance software. This system requires updates of asset run hours and odometer values, which TG and DM devices keep track of. The WebHook is configured such that at the end of a trip, the Odo/Run Hour value for the asset is sent from TG via HTTP post to this system.
  • Duress or other alerts can be integrated into a monitoring or ticketing system - to trigger follow up actions when they occur.

If two systems need to be used in parallel and more than a few data points are required - it is best to use the multi connector option (see here) - to have device data sent to both TG and the 3rd party platform simultaneously. 


WebHooks in TG - Set Up

It is possible to get alert notifications via HTTP post. The alert service expects a 2XX HTTP response code to mark the alert as processed. Web hooks can be configured by users. 

In order to configure the Webhook, a user will need the Webhook Manage permission on their user account. 

Initial steps:


1. Enable Webhooks for the organisation.

Admin ->Organisation Manage -> Organisations -> Edit.

Set the API Provider to TG Default (HTTP Post)

Select a send limit that makes sense for your use case and number of assets. The send limit is to prevent potentially misconfigured webhooks, or other issues generating thousands of alerts unchecked.



2. Configure The Webhook

Users with the Webhook Manage permission can configure the webhook via Admin -> Organisation Manage -> Webhook Manage. 

Webhooks are set up on a per-org basis (just like alerts). When creating a new webhook, you will be asked to give it a name and optional comment on the general tab. 

The Details Tab is where we determine what will be sent in the body of the webhook - and the URL to send the POST.



3. Configuring the "API Details" section and examples. 

In the below example, we want to send some asset information (Name + Serial), the Lat/Long, Speed and Trip Start location whenever the webhook is triggered. 

Note: that the body currently gets generated using string substitution which means that both a null and an empty string will result in an empty string meaning that if you choose to send a JSON object you will have to always send strings in quotes. Dates will be formatted as "yyyy-MM-ddTHH:mm:ssZ" e.g. "2017-01-31T21:23:12Z"

Name: Position Notification

URL: www.myurl.com

Headers:

Content-Type: application/json

Accept: application/json

Authorization: Basic dXNlcjpwYXNz

Body:

{{
  "device":"{Asset.DeviceSerial}",
  "name":"{Asset.Name}",
  "description":"{Asset.Description}",
  "customtext":"Some hardcoded text",
  "notificationDate":"{Event.DateReceivedUtc}",
  "latitude":"{Event.Latitude}",
  "longitude":"{Event.Longitude}",
  "speed":"{Event.SpeedKmH}",
  "zone":"{Trip.Start.Location}"
}}

We can send the headers as in the screenshot above. 

Example POST

{"device":"114719","name":"Green Van 114719","description":"","costomtext":"Some hardcoded text","notificationDate":"2017-04-23T09:31:14Z","latitude":"-26.0444252","longitude":"28.0111314","speed":"0","zone":"Depot 3"}

Note: Because string replacement is being used, data could equally be formatted as XML or CSV.


4. Set the Webhook as the recipient of an alert

We set up the webhook to send data on an event occuring. So we can send the webhook data based upon any conditions we can alert on. We simply configure an alert as normal, and under the "Notification" section, set the webhook as an address to send the alert to. It should be noted that if at the time the alert is triggered, any tokens are invalid, they will be returned null. 

I.e. tokens relating to trips won't return anything if we aren't in a trip. 


5. Testing and Debugging

To aid in testing/debugging, we have a couple of key options. 

  1. Initially, we could set up the Webhook on an alert we have easy control of - such as an Ignition On alert - while we have a device on our desk which we can ignition on/off by applying voltage to the ignition line to trigger alerts. 
  2. During testing, send the webhook data to an endpoint that requires no authorisation - so we can inspect the body and be sure all authorisation headers etc are being correctly formatted.

Available Tokens. 

{IsStart}

{DurationSeconds}

{DistanceMeters}

{MaxSpeedKmH}

{NowUtc}

{Now} - (Included for compatibility, will return UTC date)

{Duration}

{Distance}

{DistanceMiles}

{MaxSpeed}

{MaxSpeedMph}

{Asset.Name}

{Asset.Description}

{Asset.ICCID}

{Asset.MSISDN}

{Asset.AssetCode}

{Asset.DeviceSerial}

{Asset.InTripVerb}

{Asset.OutOfTripVerb}

{Asset.RegistrationNumber}

{Asset.Year}

{Asset.EngineCapacity}

{Asset.EngineNumber}

{Asset.VIN}

{Asset.ChassisNumber}

{Asset.Weight}

{Asset.Colour}

{Asset.Custom1}

{Asset.Custom2}

{Asset.Custom3}

{Asset.AssetType}

{Asset.DeviceType}

{Asset.Project}

{Asset.ProjectCode}

{Asset.Manufacturer}

{Asset.Model}

{Trip.Project}

{Trip.ProjectCode}

{Trip.TripType}

{Trip.TripTypeCode}

{Trip.Driver}

{Trip.DriverCode}

{Trip.Start.Latitude}

{Trip.Start.Longitude}

{Trip.Start.Date} - (Included for compatibility, will return UTC date)

{Trip.Start.DateUtc}

{Trip.Start.Location}

{Trip.Start.LocationComment}

{Trip.Start.Odometer}

{Trip.Start.OdometerMiles}

{Trip.Start.RunHours}

{Trip.Start.RunHoursDecimal}

{Trip.Start.RunHoursSeconds}

{Trip.Start.RunHoursTimespan}

{Trip.End.Latitude}

{Trip.End.Longitude}

{Trip.End.Date} - (Included for compatibility, will return UTC date)

{Trip.End.DateUtc}

{Trip.End.Location}

{Trip.End.LocationComment}

{Trip.End.Odometer}

{Trip.End.OdometerMiles}

{Trip.End.RunHours}

{Trip.End.RunHoursDecimal}

{Trip.End.RunHoursSeconds}

{Trip.End.RunHoursTimespan}

{Trip.Distance}

{Trip.DistanceMiles}

{Trip.DistanceMeters}

{Trip.Duration}

{Trip.DurationSeconds}

{Event.Name}

{Event.Comment}

{Event.Altitude}

{Event.AltitudeFeet}

{Event.Date} - (Included for compatibility, will return UTC date)

{Event.DateUtc}

{Event.DateReceived} - (Included for compatibility, will return UTC date)

{Event.DateReceivedUtc}

{Event.GpsFix}

{Event.HeadingDegrees}

{Event.Heading} - this is the Cardinal Heading (N, NE, E, SE, S, SW, W, NW)

{Event.Latitude}

{Event.Longitude}

{Event.PDOP}

{Event.PositionAccuracy}

{Event.SpeedAccuracy}

{Event.SpeedKmH}

{Event.SpeedMpH}

{Event.Analog1Raw}

{Event.Analog2Raw}

{Event.Analog3Raw}

{Event.Analog4Raw}

{Event.Analog5Raw}

{Event.Analog6Raw}

{Event.Analog7Raw}

{Event.Analog8Raw}

{Event.Analog9Raw}

{Event.Analog10Raw}

{Event.Analog11Raw}

{Event.Analog12Raw}

{Event.Analog13Raw}

{Event.Analog14Raw}

{Event.Analog15Raw}

{Event.Analog16Raw}

{Event.Analog17Raw}

{Event.Analog18Raw}

{Event.Analog19Raw}

{Event.Analog20Raw}

{Event.DigitalOutputsRaw}

{Event.DigitalInputsRaw}


Did you find it helpful? Yes No

Send feedback
Sorry we couldn't be helpful. Help us improve this article with your feedback.