Use variables from events in alerts - Hologram Documentation

When an event triggers an alert, the event’s data is available as variables that you insert into the email or webhook you send. You don’t create this data yourself — Hologram populates it from the event, and each variable is replaced with a real value at the moment the notification is sent.

Accessing data from an event

What a variable contains depends on which of two kinds of event fired:

Events that carry a message from your device or network — SMS, TCP/UDP, and socket API messages. Here <<decdata>> is exactly what the device sent, which can be plain text or a JSON object.
System-generated events — Data warnings, data limits, IMEI changes, and similar. Your device sends nothing; Hologram builds a defined JSON payload, so <<decdata>> is a predictable object whose fields you can reference individually (for example, <<decdata.msg>>).

For the full list of events and their tags, see Event types and tags.

Where variable values come from

Excepting the device payload in <<decdata>>, you don’t author any of the event data, you reference it. For a data warning event, for example:

<<received>> → when Hologram received the event, such as 2026-07-16T17:51:47+00:00
<<tags>> → the event’s tags, such as ["_DEVICE_1234567_", "_DATAWARNING_"]
<<device.name>> and <<device.id>> → the SIM’s name and device ID
<<data>> → the raw payload, base64-encoded; <<decdata>> → that same payload, decoded to { "msg": "Device 1234567 has hit usage warning threshold.", … }

The full event versus its payload

Those variables each read a specific part of the event — none of them returns the whole thing. When you view an event in event history or through the events API, you see a wrapper of metadata around the message, and <<decdata>> returns only the innermost, decoded payload. Here is a complete IMEI change event, decoded:

{
  "id": 100000001,
  "logged": "2026-05-13 16:40:39",
  "expires": "2027-05-13 16:40:39",
  "orgid": 12345,
  "deviceid": 1234567,
  "record_id": "11111111-2222-3333-4444-555555555555",
  "device_metadata": "{}",
  "data": {
    "authtype": "deviceid",
    "source": 1234567,
    "tags": ["_IMEI_TAC_CHANGE_", "_DEVICE_1234567_", "_IMEI_CHANGE_"],
    "data": {
      "new_imei": "351111110000001",
      "prev_imei": "350000000000000",
      "msg": "Device 1234567 IMEI change from 350000000000000 to 351111110000001"
    },
    "received": "2026-05-11T17:02:45+00:00",
    "record_id": "11111111-2222-3333-4444-555555555555",
    "device_id": 1234567,
    "device_name": "My Device"
  },
  "matched_rules": [],
  "tags": ["_IMEI_TAC_CHANGE_", "_IMEI_CHANGE_", "_DEVICE_1234567_"],
  "simcardid": 7654321
}

From that event, the variables resolve like this:

<<decdata>> returns only the innermost data — the decoded message payload, not the wrapper around it:

{
  "new_imei": "351111110000001",
  "prev_imei": "350000000000000",
  "msg": "Device 1234567 IMEI change from 350000000000000 to 351111110000001"
}

<<data>> returns that same payload before decoding, as a base64 string.
<<received>>, <<tags>>, <<device.name>>, and <<device.id>> read the surrounding fields (received, tags, device_name, and device_id) — not the payload.

Variables available in alerts

Variables are replaced with literal text when the notification is sent. When you use a variable inside a JSON payload, whether to wrap it in quotes depends on the type of value it is replaced with:

Variable	Replaced with	In a JSON payload
`<<received>>`	ISO 8601 UTC timestamp of when Hologram received the event	Wrap in quotes: `"<<received>>"`
`<<tags>>`	JSON array of the event’s tags (e.g. `["_DEVICE_1234567_", "_DATAWARNING_"]`)	Do not wrap in quotes: `<<tags>>`
`<<device.name>>`	The name of the SIM	Wrap in quotes: `"<<device.name>>"`
`<<device.id>>`	The integer device ID. SIM IDs are not yet supported	Either works: `<<device.id>>` (number) or `"<<device.id>>"` (string)
`<<data>>`	The raw payload, base64-encoded	Wrap in quotes: `"<<data>>"`
`<<decdata>>`	The decoded payload — plain text or a JSON object, depending on the event	Quote it (`"<<decdata>>"`) when the payload is plain text; leave it unquoted when the payload is JSON. See the two sections below.
`<<decdata.fieldName>>`	A single field from the payload, when the payload is JSON (e.g. `<<decdata.msg>>`)	Match the field’s type: unquoted for numbers, quoted for strings

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.

Events that carry a device or network message

For these events, <<decdata>> is the message your device or the network sent. Hologram doesn’t change it — whatever was transmitted is what you receive. Events in this category include:

Socket API messages — the device sends data directly to the Hologram socket API, as plain text or JSON.
SMS — inbound and outbound messages. <<decdata>> is the message text.
TCP/UDP messages — <<decdata>> is the message the device sent.

Because the content is whatever your device sends, whether to quote <<decdata>> depends on what it transmits:

If your device sends plain text, wrap it in quotes so it forms a valid JSON string: "<<decdata>>".
If your device sends a JSON object, leave it unquoted so it nests as an object.

Example: Forward a device reading to a webhook

A device that reports { "temperature": 23.5 } can be forwarded to a downstream service:

URL – https://example.com/webhook

Body

{
  "temperature": <<decdata.temperature>>,
  "source_device": "<<device.id>>",
  "datetime": "<<received>>"
}

…results in a POST request with the following body:

{
  "temperature": 23.5,
  "source_device": "1234567",
  "datetime": "2026-07-16T17:53:09+00:00"
}

System-generated event data

For these events, your device sends nothing. Hologram generates the event and builds a defined JSON payload, so <<decdata>> is a predictable object — and you can pull individual fields with <<decdata.fieldName>> (for example, <<decdata.msg>>). The following payloads show what <<decdata>> contains for each system-generated event.

Data warning threshold reached — _DATAWARNING_

Sent when a SIM crosses a data warning threshold.

{
  "msg": "Device 1234567 has hit usage warning threshold.",
  "deviceid": "1234567",
  "data_warning_threshold_bytes": 1,
  "triggered_at_usage_bytes": 1200
}

Data limit reached and SIM paused — _DATALIMIT_

Sent when a SIM reaches its data limit and is paused.

{
  "deviceid": "1234567",
  "plan_amount": 1024,
  "overage_limit": 500,
  "planid": 123,
  "msg": "Device 1234567 paused due to data limit"
}

First IMEI recognized — _IMEI_FIRST_

Sent the first time an IMEI is detected for a SIM.

{
  "new_imei": "350000000000018",
  "msg": "Device 1234567 first attach with 350000000000018"
}

IMEI change — _IMEI_CHANGE_

Sent when the IMEI for a SIM changes between sessions. When the TAC prefix also changes, the event additionally carries the _IMEI_TAC_CHANGE_ tag.

{
  "new_imei": "351111110000001",
  "prev_imei": "350000000000000",
  "msg": "Device 1234567 IMEI change from 350000000000000 to 351111110000001"
}

SMS delivered — _SMS_DT_DELIVERED_

Sent when an SMS is delivered to a SIM. This payload is plain text, not JSON, so wrap it in quotes when using it in a JSON body: "<<decdata>>".

SMS delivered

Conductor configuration change — _EUICC_CONFIGURE_SIM_

Sent as Conductor applies an eSIM profile configuration change. The configuration_plan array lists one entry per action, each with its own status (such as PLANNED, PENDING, COMPLETE, or ERROR).

{
  "event_type": "orchestration.euicc",
  "notification_kind": "configuration_run_updated",
  "occurred_at": "2026-05-11T20:16:41+00:00",
  "status": "PENDING",
  "device_context": {
    "device_id": 1234567,
    "sim_id": 7654321,
    "org_id": 12345,
    "last_known_imei": "350000000000000",
    "eid": "89000000000000000000000000000001"
  },
  "request_id": "aaaaaaaa-1111-2222-3333-444444444444",
  "operation_id": "bbbbbbbb-1111-2222-3333-444444444444",
  "config_change": {
    "enabled_iccid": "8988000000000000001",
    "disabled_iccids": ["8988000000000000002", "8988000000000000003"]
  },
  "configuration_plan": [
    {
      "action": "AUDIT",
      "profile_iccid": null,
      "status": "COMPLETE",
      "metadata": {
        "last_updated_at": "2026-05-11T16:15:56.993645+00:00",
        "profiles": {
          "8988000000000000003": { "state": "Disabled", "fallback_attribute": false, "delete_restriction": true },
          "8988000000000000002": { "state": "Enabled", "fallback_attribute": true, "delete_restriction": false },
          "8988000000000000001": { "state": "Disabled", "fallback_attribute": false, "delete_restriction": false }
        }
      },
      "sync_sim_to_audit": false
    },
    {
      "action": "ENABLE",
      "profile_iccid": "8988000000000000001",
      "status": "PENDING",
      "metadata": {
        "last_updated_at": "2026-05-11T20:16:41.818236+00:00",
        "attempts": 1
      }
    },
    {
      "action": "AUDIT",
      "profile_iccid": null,
      "status": "PLANNED",
      "metadata": { "last_updated_at": "2026-05-11T16:15:40.208609+00:00" },
      "sync_sim_to_audit": true
    }
  ]
}

Example: Reference specific fields from a system event

Because system payloads are structured, reference the fields you need instead of sending the whole object. Send a readable summary by email:

Recipients – ops@example.com
Subject – Usage warning for <<device.name>>
Message – <<decdata.msg>> (device <<decdata.deviceid>>)

Or forward selected fields to a webhook:

URL – https://example.com/webhook

Body

{
  "device": "<<decdata.deviceid>>",
  "message": "<<decdata.msg>>",
  "usage_bytes": <<decdata.triggered_at_usage_bytes>>,
  "at": "<<received>>"
}

Note the field types: usage_bytes is a number, so it is unquoted, while the string fields are wrapped in quotes.

Formatting and validating your payload

Important: If you are sending a JSON payload, make sure your webhook includes a content-type: application/json header. Without it, the recipient may receive an empty or unparseable body. The dashboard adds this header automatically when it detects a JSON payload, and validates that the payload is valid JSON before saving.

These payloads look similar to valid ones but are invalid and will fail to send:

{'temperature': <<decdata.temperature>>}   ← single quotes are not valid JSON
{"tags": "<<tags>>"}                       ← <<tags>> must not be wrapped in quotes
{"datetime": <<received>>}                 ← string variables must be wrapped in quotes

For help diagnosing failed alerts and webhooks, see Troubleshooting alerts and webhooks.

​Accessing data from an event

​Where variable values come from

​The full event versus its payload

​Variables available in alerts

​Events that carry a device or network message

​Example: Forward a device reading to a webhook

​System-generated event data

​Example: Reference specific fields from a system event

​Formatting and validating your payload

Accessing data from an event

Where variable values come from

The full event versus its payload

Variables available in alerts

Events that carry a device or network message

Example: Forward a device reading to a webhook

System-generated event data

Example: Reference specific fields from a system event

Formatting and validating your payload