Alert Notifications through WebHooks
Learn how to create automated alerts and notifications using WebHooks.
Written by Matthew Clark-Massera
Updated at March 13th, 2024
Table of Contents
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. It is an example of a 'push' message as based on an event, Telematics Guru will push some data to another system.
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 (or even all the live data) - 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 Managepermission on their user account.
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.
2. Configure The Webhook
Users with the Webhook Manage permission can configure the webhook via Admin → Web Hooks
Webhooks are set up on a per-org basis (just like alerts).
2.1 Create a New Webhook
2.2 Give the Webhook a name and description
No specific requirements, this can be whatever makes sense
2.3 Enter URL, Headers and Body
On the details tab, enter the URL, any headers, and the webhook body.
Add Token will bring up the list of available tokens,
These are dynamic fields based on the device data. The data from whichever device generated the webhook will be included.
2.4 Testing
The Test tab allows us to preview and test the generated webhook. Tokens are filled with Generic data, i.e. "Joe's Crane".
Edit Tokens lets us the token data.
Pressing Execute will send the webhook and return the response from the end server.
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.
- 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.
- During testing, send the webhook data to an endpoint that requires no authorisation (e.g. RequestBin) - so we can inspect the body and be sure all authorisation headers etc are being correctly formatted.
Available Tokens
{Asset.Name}
{Asset.Description}
{Asset.MSISDN}
{Asset.ICCID}
{Asset.AssetCode}
{Asset.DeviceSerial}
{Asset.InTripVerb}
{Asset.OutOfTripVerb}
{Asset.AssetType}
{Asset.DeviceType}
{Asset.Project}
{Asset.ProjectCode}
{Asset.RegistrationNumber}
{Asset.Year}
{Asset.EngineCapacity}
{Asset.EngineNumber}
{Asset.VIN}
{Asset.ChassisNumber}
{Asset.Weight}
{Asset.Colour}
{Asset.Manufacturer}
{Asset.Model}
{Asset.Department}
{Asset.DepartmentCode}
{Asset.Custom1}
{Asset.Custom2}
{Asset.Custom3}
{Trip.Project}
{Trip.ProjectCode}
{Trip.TripType}
{Trip.TripTypeCode}
{Trip.Driver}
{Trip.DriverCode}
{Trip.Distance}
{Trip.DistanceMiles}
{Trip.DistanceMeters}
{Trip.Duration}
{Trip.DurationSeconds}
{Trip.Start.Date:default:dd/MM/yyyy}
{Trip.Start.Date:default:HH:mm}
{Trip.Start.Date:default:dd/MM/yyyy HH:mm}
{Trip.Start.DateUtc:default:dd/MM/yyyy}
{Trip.Start.DateUtc:default:HH:mm}
{Trip.Start.DateUtc:default:dd/MM/yyyy HH:mm}
{Trip.Start.Location}
{Trip.Start.LocationComment}
{Trip.Start.Latitude}
{Trip.Start.Longitude}
{Trip.Start.Odometer}
{Trip.Start.OdometerMiles}
{Trip.Start.RunHours}
{Trip.Start.RunHoursDecimal}
{Trip.Start.RunHoursSeconds}
{Trip.Start.RunHoursTimespan}
{Trip.End.Date:default:dd/MM/yyyy}
{Trip.End.Date:default:dd/MM/yyyy HH:mm}
{Trip.End.Date:default:HH:mm}
{Trip.End.DateUtc:default:dd/MM/yyyy}
{Trip.End.DateUtc:default:dd/MM/yyyy HH:mm}
{Trip.End.DateUtc:default:HH:mm}
{Trip.End.Location}
{Trip.End.LocationComment}
{Trip.End.Latitude}
{Trip.End.Longitude}
{Trip.End.Odometer}
{Trip.End.OdometerMiles}
{Trip.End.RunHours}
{Trip.End.RunHoursDecimal}
{Trip.End.RunHoursSeconds}
{Trip.End.RunHoursTimespan}
{Event.Name}
{Event.AltitudeFeet}
{Event.Date:default:dd/MM/yyyy}
{Event.Date:default:HH:mm}
{Event.Date:default:dd/MM/yyyy HH:mm}
{Event.DateUtc:default:dd/MM/yyyy}
{Event.DateUtc:default:HH:mm}
{Event.DateUtc:default:dd/MM/yyyy HH:mm}
{Event.DateReceived:default:dd/MM/yyyy}
{Event.DateReceived:default:HH:mm}
{Event.DateReceived:default:dd/MM/yyyy HH:mm}
{Event.DateReceivedUtc:default:dd/MM/yyyy}
{Event.DateReceivedUtc:default:HH:mm}
{Event.DateReceivedUtc:default:dd/MM/yyyy HH:mm}
{Event.GpsFix}
{Event.GeoFence}
{Event.GeoFenceComment}
{Event.HeadingDegrees}
{Event.Latitude}
{Event.Longitude}
{Event.PDOP}
{Event.PositionAccuracy}
{Event.SpeedAccuracy}
{Event.SpeedKmH}
{Event.SpeedMpH}
{Event.TagBatteryVoltage}
{Event.TagRSSI}
{IsStart}
{Now:default:dd/MM/yyyy}
{Now:default:HH:mm}
{Now:default:dd/MM/yyyy HH:mm}
{NowUtc:default:dd/MM/yyyy}
{NowUtc:default:HH:mm}
{NowUtc:default:dd/MM/yyyy HH:mm}
{Duration}
{DurationSeconds}
Webhook Example
In this example, the webhook sends the following tokens -
- Event Date and Time in UTC using {Event.DateUtc} in the dd/MM/yyyy HH:mm format
- Device Serial number using {Asset.DeviceSerial}
- GPS Latitude and Longitude using {Event.Latitude} and {Event.Longitude}
- Speed using {Event.SpeedKmH}
- Static value when 'betaMode' is true
Some 3rd party platforms where the webhooks are pointing to, might have some format requirements to be able to successfully accept data. This may include the use of fields name such as utc_located_at and static values in the body, in this example, the webhook is pushing data to a developer/beta server which requires 'betaMode' needs to be true.
Note - {Event.SpeedKmH} provides speed as a whole number eg. 45. 3rd party platforms may require a float/decimal number eg. 45.01. TG does not receive speed data with decimals. To satisfy this requirement, we can hardcode a decimal in the webhook body eg. {Event.SpeedKmH}.01 
Output -
