Overview

Webhooks provide event based triggers for receiving Tive alert or device data. In the Tive ecosystem, webhooks are associated at the Account level and can be triggered by one or more of the following data stream system events:

Data Streams

When you're setting up a webhook you should specify which data streams you would like to receive events for:

All Tracker Data Streams

A webhook event will trigger whenever a new device measurement is received. The frequency of events will depend on the measurement interval you have selected for your device(s) and their connectivity. Data from this stream will be in the Device Data Stream format.

If you're using the API to create or update a webhook, this stream is enabled via the applyToAllTrackers flag.

All Shipment Events

This is similar to the "All Tracker Data Streams" and sends the same type of data, but will filter only for device measurements only when the device is associated to an active shipment. Data from this stream will be in the Device Data Stream format.

If you select this stream on the same webhook with the "All Tracker Data Streams" option it will have no effect, as all device data points will already be included.

If you're using the API to create or update a webhook, this stream is enabled via the applyToAllShipments flag.

All Alert Notifications

A webhook event will be sent every time there is an alert notification.

Our alerts can be separated into two categories,

• Point-in-time Alerts: These happen at one specific time. This includes shock, light, arrival, and departure alerts. A notification is sent for these as soon as we see them happen.
• Date Range Alerts: These have a start and end date and include all other types of alerts (such as Temperature, Battery, Geofence-based, etc.). For these we send a notification as soon as we see it begin and another when we see it end or resolve. For example, a notification would be sent for a temperature alert once we see it out of the specified range, and another "closing" it once we see it back within the acceptable range. You can use the Alert.IsClosed flag to differentiate the start and end for these, and the Alert.AlertId properties to correlate the start and end events if needed.

Data from this stream will be in the Alert Data Structure format.

If you're using the API to create or update a webhook, this stream is enabled via the applyToAllAlertPresets flag.

URL

Specifies where you would like the webhook payload to go. This could be a company Slack channel, Salesforce instance, or Transportation Management System (TMS).

You may also provide an email address as well if you like. To do so, the URL field must be formatted as follows: email://[email protected].

Custom Headers

Tive webhooks also support adding custom headers. When a webhook event is triggered, the HTTP request will include the custom header(s) associated. These custom headers can be used to supplement any additional security scheme, such as an internal client id/secret, or any other data needed as part of your typical workflow.

You may use the custom header to specify a customer header such as x-api-key. These custom headers can also be used to perform [basic access authentication](HTTP Basic authentication) by providing Authorization as the header key, and a value of Basic {credentials} where credentials is the Base64 encoding of an ID and password separated by a single colon.

Templates

If you need your data in a specific format, don't worry, Tive lets you do that!

Message Format

Templating is a key concept for webhook definitions. When a template is left empty, the default JSON representation of an event is used as the body of the message. When a template is configured, a user can control the formatting of the message.

The following JSON shows an example custom template created on the platform:

{
   "latitude": {Location.Latitude},
   "longitude": {Location.Longitude},
   "temperature": {Temperature.Celsius},
   "utcTime": {EntryTime.Utc},
   "shipment": {ShipmentId},
   "myCustomData": "Here is my custom non-Tive data"
}

To create the same custom template via API, the template field in the Create a Webhook or Update a Webhook endpoints would look like this within a request:

{
     "template": "{\"latitude\": {Location.Latitude},\"longitude\": {Location.Longitude},\"temperature\": {Temperature.Celsius},\"utcTime\": {EntryTime.Utc},\"shipment\": {ShipmentId},\"myCustomData\": \"Here is my custom non-Tive data\"}",
     "name": "Custom Template Via API",
     "url": "https://www.example.com/webhooksGoHere",
     "enabled": true,
     "applyToAllTrackers": true
}

A Few Notes on Template Variables

• Template Variables are defined using curly braces: {MyVariable}.
• The Tive system will replace Template Variables with their value or “N/A” if the variable name is unknown or has no value.
• Valid variable names utilize letters and the ‘.’ (dot) character.
• The complete list of variable names available can be found here.

Additional Security Notes

• Webhook requests will originate from the source IP adress 34.195.102.163, some networks block traffic from unapproved sources so you may need to add this as a trusted source.
• You may use Webhook Signatures to provide an additional layer of security to ensure outside parties do not attempt to transmit data to your webhook.