> ## 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. # Use variables from events in alerts > Use variables to reference event data and insert into Alert email and webhook notifications sent to your team or systems. 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 `<>` 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 `<>` is a predictable object whose fields you can reference individually (for example, `<>`). For the full list of events and their tags, see [Event types and tags](/guides/cloud-and-tools/event-types-and-tags). ### Where variable values come from Excepting the device payload in `<>`, you don't author any of the event data, you reference it. For a data warning event, for example: * `<>` → when Hologram received the event, such as `2026-07-16T17:51:47+00:00` * `<>` → the event's tags, such as `["_DEVICE_1234567_", "_DATAWARNING_"]` * `<>` and `<>` → the SIM's name and device ID * `<>` → the raw payload, base64-encoded; `<>` → 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](/dashboard/event-monitoring/event-history) or through the events API, you see a wrapper of metadata around the message, and `<>` returns only the innermost, decoded payload. Here is a complete IMEI change event, decoded: ```json theme={null} { "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: * `<>` returns **only** the innermost `data` — the decoded message payload, not the wrapper around it: ```json theme={null} { "new_imei": "351111110000001", "prev_imei": "350000000000000", "msg": "Device 1234567 IMEI change from 350000000000000 to 351111110000001" } ``` * `<>` returns that same payload *before* decoding, as a base64 string. * `<>`, `<>`, `<>`, and `<>` 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 | | ----------------------- | ---------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | `<>` | ISO 8601 UTC timestamp of when Hologram received the event | Wrap in quotes: `"<>"` | | `<>` | JSON array of the event's tags (e.g. `["_DEVICE_1234567_", "_DATAWARNING_"]`) | Do **not** wrap in quotes: `<>` | | `<>` | The name of the SIM | Wrap in quotes: `"<>"` | | `<>` | The integer device ID. *SIM IDs are not yet supported* | Either works: `<>` (number) or `"<>"` (string) | | `<>` | The raw payload, base64-encoded | Wrap in quotes: `"<>"` | | `<>` | The decoded payload — plain text or a JSON object, depending on the event | Quote it (`"<>"`) when the payload is plain text; leave it unquoted when the payload is JSON. See the two sections below. | | `<>` | A single field from the payload, when the payload is JSON (e.g. `<>`) | Match the field's type: unquoted for numbers, quoted for strings | **Important:** The `<>` 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 `"<>"` produces an invalid JSON string, while `<>` (without quotes) produces a valid array. ## Events that carry a device or network message For these events, `<>` 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. `<>` is the message text. * **TCP/UDP messages** — `<>` is the message the device sent. Because the content is whatever your device sends, whether to quote `<>` depends on what it transmits: * If your device sends **plain text**, wrap it in quotes so it forms a valid JSON string: `"<>"`. * 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** ```json theme={null} { "temperature": <>, "source_device": "<>", "datetime": "<>" } ``` ...results in a `POST` request with the following body: ```json theme={null} { "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 `<>` is a predictable object — and you can pull individual fields with `<>` (for example, `<>`). The following payloads show what `<>` contains for each system-generated event. Sent when a SIM crosses a data warning threshold. ```json theme={null} { "msg": "Device 1234567 has hit usage warning threshold.", "deviceid": "1234567", "data_warning_threshold_bytes": 1, "triggered_at_usage_bytes": 1200 } ``` Sent when a SIM reaches its data limit and is paused. ```json theme={null} { "deviceid": "1234567", "plan_amount": 1024, "overage_limit": 500, "planid": 123, "msg": "Device 1234567 paused due to data limit" } ``` Sent the first time an IMEI is detected for a SIM. ```json theme={null} { "new_imei": "350000000000018", "msg": "Device 1234567 first attach with 350000000000018" } ``` 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. ```json theme={null} { "new_imei": "351111110000001", "prev_imei": "350000000000000", "msg": "Device 1234567 IMEI change from 350000000000000 to 351111110000001" } ``` 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: `"<>"`. ```text theme={null} SMS delivered ``` 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`). ```json theme={null} { "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 <>` * **Message** – `<> (device <>)` Or forward selected fields to a webhook: * **URL** – `https://example.com/webhook` * **Body** ```json theme={null} { "device": "<>", "message": "<>", "usage_bytes": <>, "at": "<>" } ``` 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: ```text theme={null} {'temperature': <>} ← single quotes are not valid JSON {"tags": "<>"} ← <> must not be wrapped in quotes {"datetime": <>} ← string variables must be wrapped in quotes ``` For help diagnosing failed alerts and webhooks, see [Troubleshooting alerts and webhooks](/guides/troubleshooting/troubleshooting-alerts-and-webhooks).