Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.hologram.io/llms.txt

Use this file to discover all available pages before exploring further.

Beta: Alerts functionality is in beta and replaces our legacy Routes functionality. Some Routes functionality is no longer available, and you may find issues during the beta period. Please send us your feedback using the Support menu in your dashboard.

​
Creating an alert

Alerts provide a way to subscribe to and receive notifications for events created in the Hologram Cloud across your fleet. These events are displayed the Event history page in your dashboard. These events are created after specific events occur in your fleet, and are tracked using Event tags that are attached to each event.

Read about event tags and event types

When you create an alert, you can select the event types you want to subscribe to, the devices or tags you want to target, and the notification method you want to use. You can manage alerts by navigating to the Event monitoring section in the main menu and clicking the Alerts tab. You can also manage alerts for a single SIM from the SIM’s Alerts tab.

How to create an alert to get notified when events occur

​
Accessing data from an event

When you create an alert, the data from the event is available to use in the notification you generate and send. This can be a string of text or a JSON object, depending on the event created, how it was generated, and how you originally triggered the event. For example, when sending a simple SMS message to a SIM you can reference the message data directly. Or if you sent a full JSON payload, you can reference specific fields and format your notification using the data from the event. This data is available from variables that are available to use in the notification you generate and send.

​
Event variables available to use in alerts

  • <<received>> - ISO8601 UTC timestamp when Hologram received the message
  • <<tags>> - Array of event tags attached to the event (e.g. _DEVICE_12345_, _SMS_DO_). See note below about using this variable in JSON payloads.
  • <<device.name>> - The name of the SIM
  • <<device.id>> - The device ID. SIM IDs are not yet supported
  • <<data>> - Base64-encoded payload
  • <<decdata>> - Decoded payload (if text)
  • <<decdata.fieldName>> - Access a JSON field if the payload is JSON (e.g. <<decdata.voltage>>)
Important: The <<tags>> variable is replaced with a JSON array (e.g. ["_DEVICE_12345_", "_SMS_DO_"]). When using this variable in a JSON webhook body, do not wrap it in quotes. Writing "<<tags>>" produces an invalid JSON string, while <<tags>> (without quotes) produces a valid array.

​
Example: Send an email containing the message data from an event

  • Recipients – kiera.bennett@hlgresearch.com
  • Subject – Data limit reached for <<device.name>>
  • Message – Device ID: <<device.id>> // Message: <<decdata>>
The above example uses the <<decdata>> variable which refers to the “decoded data” in the message body. Data is usually encoded in Base64 when being transmitted. However, when a notification is sent, the message body will be populated with the actual message data before the notification is sent.

​
Example: Send a webhook containing specific fields from an event

Variables can also be directly referenced within messages, so that you send specific message formats to your downstream services. Sending a message to a webhook with the following format…
  • URL – https://example.com/webhook
  • Body 
    {
  "temperature": <<decdata.temperature>>,
  "source_device": "<<device.id>>",
  "datetime": "<<received>>"
}
…would result in a POST request sent to your webhook with the following message body: 
{
  "temperature": 23.5,
  "source_device": "12345",
  "datetime": "2018-09-27T18:53:09.302915"
}
Important: If you are sending a JSON payload, make sure to select JSON as the content type in the webhook configuration. Without the correct Content-Type header, the recipient may not parse the payload correctly.

​
Supported notification methods

​
Email notifications

Sends an email with the specified subject and body to one or more recipients.
Email notification example

​
Parameters

  • Recipients - Comma-separated list of email addresses.
  • Subject - Subject line for the email.
  • Message - Template for the body of the message.

​
Webhook notifications

If you need to send messages to an app or service that Hologram doesn’t natively support, you can send notifications using webhooks to send an HTTP POST request to any URL. This is useful for integrating with your own web apps, or services like Zapier, Make, or Slack.
Note: 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 alert, then refresh the RequestBin inspector page after you trigger the event that the alert is subscribed to. The message you receive will let you see the HTTP headers and content of the message that you can expect.
You can also send template variables in the destination URL. This is useful for sending data as URL query string parameters. For example, the URL: 
https://example.com/webhook?device=<<device.id>>&data=<<data>>
Will send the <<device.id>> and <<data>> variables as query string parameters.

​
Webhook configuration

When configuring a webhook notification, you will need to specify the following fields:
  • Destination URL — The URL that receives the POST request. You can include variables in the URL to pass data as query string parameters.
  • Message payload for POST — The body of the request. Use variables to customize the message content. The default value is <<decdata>>, which is the decoded payload of the event (either a string or JSON object).
  • Content type — Choose whether to send the payload as JSON (application/json) or form-encoded (application/x-www-form-urlencoded). If your payload contains JSON, select JSON.
  • Headers for POST — Add custom headers as key-value pairs. Click Add basic auth header to include an Authorization header for authenticated requests.

​
Deprecated Routes functionality

The following functionality was part of our legacy Routes functionality and is no longer supported. Some of these features will still work for some time, but any unsupported alerts will not be editable in your dashboard, and will be removed in a future release:
  • SMS notifications (deprecated in early 2023)
  • Slack legacy webhooks
  • IFTTT webhooks
  • Losant webhooks
  • Losant device send state
  • Amazon S3 routing
  • Heartbeat triggers (currently supported only via the API)

​
Frequently asked questions

No, alerts are processed after an event occurs, and could take anywhere from a few seconds to a few minutes to be processed and sent.
No, notifications are sent as they happen. However, if this would be useful for your organization, please send us a request using the Feedback button in the Support menu in your dashboard.
Yes, by creating multiple alerts, or subscribing to all events of a specific type. The best way is to tag your SIMs and subscribe to that SIM tag. The event tags checked by Alerts are inclusive, so if you add multiple tags to an alert it must match all of those tags for the alert to be triggered. If multiple _DEVICE_ID_ tags were added to a data limit alert, for example, the alert could never trigger.

How to create an alert

Event types and event tags

Troubleshooting alerts and webhooks