Creating a New Webhook
Creating a Webhook for Slack (With Example)
Viewing and Editing Existing Webhooks
Applying a Webhook to an Alert Profile
Applying a Webhook to a Tracker Data Stream
Testing a Webhook
Technical Documentation  

 

Webhooks enable you to receive push notifications associated with alerts or tracker data streams on channels outside of the Tive system, such as Slack or your internal data collection systems.

For example, you can set up a Webhook to funnel particular data streams, such as temperature or location, directly into your internal system, so that you always have access to the information you need (instead of needing to log in to the Tive platform to access the data). Or if you just want to receive alert notifications, you can set up a Webhook to inform you when an Alert Profile is triggered (such as a geofence alert, a temperature excursion, or a shock event).

Below is a sample notification from a Webhook set up to send location and temperature data from a tracker data stream to a Slack channel:

 

Creating a New Webhook

To create a new Webhook, open the User menu on the top right corner of the screen and select "Account". Note that the "Account" menu item is restricted to Admin users. If you are not an Admin, contact an Admin from your team that can upgrade your permissions.

From within the "Account" section, navigate to “Webhooks” page and click “Create a Webhook” button.

 

 

Enter the Name, URL, and Description for your Webhook. You must enter a unique Name and URL for successful Webhook configuration. The Description is optional. In addition, if you would like to configure Headers or Templates, click “Configure Advanced Settings”. Note that if you need the data in a specific format, you will need to add a custom Template. If you leave the Template blank, it will send the data in the default format (shown in our technical documentation here). As such, to configure a Webhook for Slack, you will need to enter a custom Template (see below for details). When you are finished, click “Create”. Your new Webhook will now be listed in the list of available Webhooks.

 

Creating a Webhook for Slack (With Example)

Here we will go through a step-by-step example for creating a Webhook to send tracker data to a Slack channel. First, follow all steps outlined in Creating a New Webhook.

Once in the creation form, enter a unique Name and a Description for the Webhook.

Next, you will need to add a URL associated with the Webhook. The instructions below explain how to get a URL for a Webhook to send notifications to a Slack channel.

Getting a URL for a Slack Webhook:

Open a web browser and navigate to your company’s Slack apps page (For Tive, this is “tiveinc.slack.com/apps”. Replace “tiveinc” with your company’s account name.). If you are not already logged in, click “Sign In” in the top right and enter your Slack account name, username, and password to log in. Once on your company’s Slack apps page, scroll down to the search bar, type “WebHooks”, and select the “Incoming WebHooks” app.

On the Incoming WebHooks app page, click the green “Add Configuration” button to create a new URL. If you do not see the green “Add Configuration” button, talk to someone in your IT department about installing the “Incoming WebHooks” Slack app for your company’s Slack account.

After you click “Add Configuration”, scroll to the bottom of the page and select the Slack channel that you would like to receive the notifications. Click “Add Incoming WebHooks integration” to continue.

Scroll down to the “Setup Instructions” section and copy the URL listed next to “Webhook URL”. This is the URL that you will need to input on the Tive software platform.

When you are finished, click the green “Save Settings” button at the bottom of the page. Now, go back to the Tive software platform and paste the URL into the box.

Once you have entered the URL, click “Configure Advanced Settings” to expand the Templates and Headers sections.

Entering a Template for a Slack Webhook:

For a Webhook to work with Slack, you have to enter a Template when you create the Webhook. Copy the sample code below and paste it into the “Templates” field to configure a Slack Webhook. When you are finished, click the green “Create” button.

Sample Slack Webhook Template: 

{ 
 "text": "*Tive Device Data Entry for Device {DeviceName}*",
 "icon_emoji": ":tive:",
 "attachments": [
 {
 "color": "good",
 "text": "Entry Time: {EntryTime.Utc} (UTC)"
 },
 {
 "color": "good",
 "text": "Location: {Location.FormattedAddress}\nLocation Coordinates: ({Location.Latitude},{Location.Longitude}) \nTemperature: {Temperature.Celsius}ºC"
 }
 ]
}

The Template configures which data streams you will receive. The sample above is set up to send a tracker’s location and temperature data streams. For details on configuring a custom Template, talk to your IT department or contact Tive support.

Developers can find more information in Tive Public API Technical Documentation sections:

• Webhooks: for an explanation on the above Webhooks template
• Appendix B > Device Data Entry Properties: for a list of properties to use in the webhook
• Appendix A > Device Data Entry: for an example of  webhook values

 

Viewing and Editing Existing Webhooks

To view your existing Webhooks, navigate to “Account” and click the “Webhooks” tab. The screen will display a list of all of your existing Webhooks.

To view details associated with a Webhook, click the Webhook in the list. A pane will open which includes the Name, URL, Description, and any headers or templates you specified when you created the Webhook.

To edit the Webhook, click “Edit” at the top of the details pane. To delete a Webhook, click the three dots next to “Edit”, and then click “Delete”.

 

Applying a Webhook to an Alert Profile

To receive tracker or shipment alerts through a Webhook, you will need to apply the Webhook to an Alert Profile, and then apply that Alert Profile to the tracker or shipment. For more information about Alert Profiles, click here.

 

 

To apply a Webhook to an existing Alert Profile, select “Alert Profiles” from the Configure menu at the top of the screen. Select the Alert Profile that you would like to connect to a Webhook, and click “Edit”. Scroll down until you reach the section titled “Assignees”. Under “Assignees”, there is a text box labeled “Push Notifications”. Click the text box and select the Webhook which you would like to apply to the Alert Profile. When you are finished, click the green “Update and Close” button at the bottom of the page.  

To apply a Webhook to a new Alert Profile, follow the instructions here to create a new Alert Profile. Then, in the “Assignees” section at the bottom of the page, click the text box labeled “Push Notifications” and select the Webhook you want to apply to the new Alert Profile. When you are finished, click the green “Save and Close” button at the bottom of the page.

Once you have finished configuring your Alert Profile to include a Webhook, be sure that you have applied your Alert Profile to the trackers or shipments for which you would like to receive push notifications. For details on applying Alert Profiles to trackers or shipments, click here.

 

Applying a Webhook to a Tracker Data Stream

To receive a Device Data Stream (all data from a tracker, not just triggered alerts) through a Webhook, you will need to apply the Webhook directly to the tracker. To do this, click “Trackers” at the top of the screen and select the tracker which you would like to connect to a Webhook. Click the “Details” tab, and scroll down to the “Data Stream” section at the bottom of the page.

If the tracker currently has no Webhooks attached to it, click “Add Webhook” and select the Webhook(s) that you want to connect. When you are finished, click “Apply”.

If the tracker already has Webhooks applied to it, they will be listed in the “Data Stream” section. If you would like to remove Webhooks or add additional Webhooks to a tracker that already has Webhooks applied to it, click “Edit” in the “Data Stream” section at the bottom of the Tracker Details page.

In the “Tracker Data Stream” pop-up panel, remove a Webhook by clicking the “X” next to that Webhook, or add new Webhooks by clicking the arrow button next to the text box and selecting the Webhook you would like to add. When you are finished, click “Apply”.

 

Testing a Webhook

Once you have created a Webhook, you can test it to make sure it is set up properly. Navigate to the Webhook details pane, expand the secondary menu, and click "Test".

In the window that pops up, select "Sample Tracker Data" or "Sample Alert Data" to choose what kind of data to use for the test. Click the green "Run Test" button to run the test.

 

Technical Documentation

Read Tive Public API Technical Documentation for in-depth Webhook configuration documentation.