GLOBAL SALES

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", "_DEVICE_12345_"],
  "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
  • device.name: Human-readable name of the device, as specified in the Hologram Dashboard
  • device.id: 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.

topicdescription
_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 originating from a device get assigned a topic containing the device ID, e.g. _DEVICE_1234_.
_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.
_SMSOVERIP_Messages that come in through our SMS-over-IP endpoint

Webhook Formats

Custom Webhook URL Rule

Method: POST

Headers:

  • 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

Headers:

  • 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.