Routes in the Hologram ecosystem provide convenient methods to trigger actions (data storage, Email, SMS, webhooks, and many more), which are triggered by the presence or even absence of a device message’s topic.
A route consists of 3 parts, which follow an ingress/egress pattern:
Most apps can include the data and meta-data from a message. To access this data when configuring the app, you can use our basic templating syntax and variables. They are accessed in the following manner:
The above example uses the <<decdata>> variable which refers to the “decoded data”, (usually encoded in Base64 when being transmitted.) This will be populated with the actual message data before the email is sent to you.</decdata>
NOTE: If the decoded data(decdata) is JSON, you can access each field with dot notation: <<decdata.foobar>></decdata.foobar>
One common use case is to construct a JSON body for a webhook app. For example, the body field could be:
Which would result in a POST request body sent to your webhook with the following:
The following are the details of the current app integrations.
NOTE: We are constantly adding to this list and are open to integrate with any service you may need.
The Modifier app transforms the format of each message using templates. This can be useful for including message metadata in the payload itself, or for decoupling the device’s message format from the format that gets sent to downstream services.
The Heartbeat app emits an event if it does not receive data from its subscribed topics for a period of time. This can be useful to generate alerts when devices go offline.
As an example, let’s create an alert to send an email when the device with ID 12345 fails to write a message for 15 minutes.
Sends an email with the specified subject and body to one or more recipients.
Slack is a group messaging application that has great support for integrating with external services. Hologram’s Slack integration posts matching messages to a configurable Slack channel.
First, generate a Slack webhook URL by visiting the Incoming Webhooks page. Make sure you’re signed into the correct Slack team, then pick which channel to route Hologram messages to. Click the Add Incoming Webhooks integration button to generate a new integration URL. From this page you can also change the icon and name that Slack displays when Hologram posts a message.
Create a Hologram route select Slack as the action app. The Slack route has three parameters:
If you need to send messages to an app or service that Hologram doesn’t natively support, you may use one of the Webhook app types to generate an HTTP POST request to any URL. This is useful for integrating with your own custom web app.
TIP: To verify the contents and format of webhooks, it can be useful to send them to an HTTP request inspector such as RequestBin. Use your generated RequestBin URL as the destination URL in the route config, then refresh the RequestBin inspector page after you send a message to the Data Engine. It should then display the HTTP headers and content of the corresponding webhook.
The Advanced Webhook Builder action app sends HTTP POST requests that you can customize via templates. This rule is more flexible than the Custom Webhook URLdestination–you can use it when the destination application expects an HTTP request in a specific format.
When sending JSON content, make sure to include the correct content-type header so that your application can process it correctly. You can do this by specifying a Content-Typeheader with a value of application/json
Some webhooks may expect a different content type. Consult the appropriate documentation for the service that you are using.
It’s also possible to include template variables in the destination URL. This is useful for sending data as URL query string parameters. For example, the URL
will send the device_id and data variables as query string parameters.
The Custom Webhook URL app has been deprecated. New applications should use the Advanced Webhook Builder instead.
The Custom Webhook URL destination sends a form-urlencoded HTTP POST request with a message’s data payload and metadata in a pre-defined format. The request includes a payload field which contains a JSON representation of the message. The payload’s format is as follows:
"tags": ["TOPIC1", "_DEVICE_12345_"],
"device_name": "My Device",
The data field contains a base64-encoded representation of the data payload.
When developing an application that accepts webhooks, it’s important to have a reliable way to check that an HTTP request is coming from the intended source. The Custom Webhook URL destination lets you specify a key to be included in every webhook that gets sent. Then, your application can check for the presence of this key to ensure that the request indeed originated from Hologram. The request body includes this string as a field called key, alongside the payload.