Data Router

For a description of Routing Rules, see the guide.

Data Message Fields

The Data Router sends these fields to downstream apps and webhook recipients by default. These fields are also available in templates for the Advanced Webhook Builder routing rule.

"received": "2016-09-27T18:53:09.302915",
"authtype": "psk",
"tags": ["TOPIC1", "DEVICE12345_"],
"device": {"id": 5678, "name": "My Device"},
"errorcode": 0,
"source": "abcd",
"timestamp": "0",
"data": "SGVsbG8sIHdvcmxkIQo="
  • received: ISO8601-formatted UTC timestamp when the message was received by the Router
  • tags: Array of topics that the message belongs to
  • Human-readable name of the device, as specified in the Hologram Dashboard
  • Integer ID of the device
  • data: Base64-encoded representation of the data payload
  • authtype: Method by which the message sender authenticated with the Data Engine
  • errorcode: 0 for messages processed successfully
  • source: Source ID from the Router credentials used to send the message. This corresponds to a specific Hologram device. Some data sources use a different authentication method so this field may not always be present.

System Topics

The Router will automatically append certain topics based on the source and protocol of the message. All system topics begin and end with an underscore character, e.g. _SIMPLESTRING_. For security and consistency reasons, you are not able to specify these system topics explicitly.

_API_RESP_When a device responds to a message sent using the cloud-to-device API or Dashboard features, the response contains this topic
_DEVICE_XXX_Messages relating to a specific device get assigned a topic containing the device ID, e.g. _DEVICE_1234_.
_IMEI_FIRST_Message indicates that we just saw the first IMEI assigned for the given device. More information will be in message body.
_IMEI_CHANGE_Message indicates the the IMEI assigned to the device has changed. More information will be in message body.
_IMEI_TAC_CHANGE_Comes along with _IMEI_CHANGE_ and indicates that not only did the IMEI change but the first 8 digits changed, meaning that this is a new type of hardware.
_JSONSTRING_Messages that come in via our socket API and use the JSON data format
_RESTAPI_Messages that come in via our REST API (as opposed to our socket API)
_SOCKETAPI_Messages that come in via our socket API (as opposed to HTTP REST API)
_SIMPLESTRING_Messages that come in via our socket API and use the string data format
_SMS_Messages that come in through our SMS-over-IP endpoint, or the Hologram SMS phone number
_SMS_DO_Messages sent to the CSR via Hologram’s SMS phone number will contain this topic.
_SMS_DT_SMS messages sent through our systems to a device will contain this topic
_SMS_DT_DELIVERED_This message indicates that an SMS that was sent to a device through our systems was marked as delivered by the network.
_SMSOVERIP_Messages that come in through our SMS-over-IP endpoint
_TAG_XXX_If the given device has a tag at the time the message is sent, then this topic will be applied for each tag with the tag ID.
_DATALIMIT_This messages indicates that a data overage limit was triggered for a device

Webhook Formats

Custom Webhook URL Rule

Method: POST


  • Content-Type: application/x-www-form-urlencoded

Form fields:

  • userid: Hologram user ID
  • payload: JSON-formatted message object
  • key: Optional webhook key as configured in routing rule
  • properties: JSON-formatted routing rule configuration:
  • url: URL that the webhook was sent to
  • user_id: Hologram user ID
  • key: Optional webhook key as configured in routing rule

Note that the payload and properties fields are JSON objects within a form-urlencoded body, so you may need to explicitly decode the JSON even if your HTTP library decodes the top-level fields in the body.

Advanced Webhook Builder Rule

Method: POST


  • Content-Type: If Send JSON Content Type is configured:application/json. Otherwise Content-Type is omitted.

Body: Determined by configured payload template.

See the Routing Rules guide for information on configuring the payload template for Advanced Webhook Builder rules.