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

All tracker data streams

A webhook event will trigger for every device measurement. The frequency of events will depend on the measurement interval you have selected for your device(s).

All shipment events

A webhook event will trigger for every device measurement only if the device is associated with an active shipment.

All alert notifications

Enabling this option will apply the webhook to all alert presets within the applicable account(s). A webhook event will subsequently be sent any time an alert gets triggered.

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.