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.
NOTE: If the decoded data(decdata) is JSON, you can access each field with dot notation: <<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:
M2X is a platform by AT&T for logging and streaming data from device sources to destinations in the cloud. M2X organizes data within devices, where each device can have one or more streams of numerical or text data. Hologram’s M2X integration forwards messages from Hologram devices to a stream on a corresponding M2X device.
In order for Hologram to authenticate to your M2X account, you must provide an M2X API master key. To find your master key, access your account settings by clicking on your account name at the top-right, then selecting Account Settings from the dropdown menu. Copy the automatically created master key from this page:
Create a Hologram route, and select AT&T M2X as the action app. The M2X route has four parameters:
Hologram relies on M2X’s Device Serial identifier for mapping between Hologram and M2X devices. Hologram routes messages from a Hologram device with ID 12345 to the M2X device with serial konekt_12345. If an M2X device with this serial doesn’t exist, Hologram will automatically create it.
If the destination device doesn’t have a stream with the given stream name, Hologram will create a non-numeric stream. This allows you to store arbitrary text payloads in M2X. However, if you pre-create a numeric stream with the given name, M2X will attempt to parse the data payload as a number. This can be useful for devices sending numeric sensor readings to the Hologram Cloud.
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.