Digital Matter Support

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. 


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 fees.


So one example is hiring or maintenance software. This system requires updates of asset run hours and odometer values. So 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. 


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 - to have device data sent to both TG and the 3rd party platform simultaneously. 


WebHooks in TG - the details

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. There is currently no UI available to partners to configure this, but you can send the following information to your local support team and they can get the end point set up as an address book entry.


Required Details

  • Organisation Name
  • Address Book Entry Name
  • URL
  • Headers
    • Content-Type (e.g. “application/json”)
    • Accept (e.g. “application/json”)
    • Custom Headers (this could include BASIC authentication)
  • Body of POST made up of tokens (see list below)


Once the details have been set up you will be able to add the endpoint as an alert recipient to any existing or new alerts.


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"


Example 

Organisation: Llama Tracking LLC

Name: Position Notification

URL:

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


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.


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.