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

# Create an alert

> Create an alert to get notified via email or webhooks when specific events occur in your fleet. Each alert subscribes to a specific event tag and listens for events that match all tags applied to the alert.

An alert watches for events in your fleet, such as a SIM reaching its data limit or falling back to another profile, and sends you an email or webhook when one occurs. Every alert has three parts:

* **Alert type**: the kind of event to watch for. Each type matches one or more event tags.
* **Scope**: every SIM in your organization, one SIM, or every SIM with a specific [tag](/dashboard/sim-actions/tag-sims).
* **Notification**: an email or a webhook, with message contents you can customize using event variables.

Events are always recorded in [Event history](/dashboard/event-monitoring/event-history), whether or not an alert is set up for them. An alert only adds the notification.

## How to create an alert

<Steps>
  <Step title="Open the Alerts page">
    Navigate to the **Event monitoring** section in the main menu and open the **Alerts** page.

    To create an alert for a single SIM, you can instead open the SIM's [Alerts tab](/dashboard/sims/sim-details-alerts-tab). The alert starts out limited to that SIM.
  </Step>

  <Step title="Choose an alert type">
    Click **Create alert** and choose the type of event you want to be notified about. See [Alert types](#alert-types) below.
  </Step>

  <Step title="Name the alert">
    In **Alert details**, give the alert a name that will help you recognize it later, like "Canada roaming - Data limit reached".
  </Step>

  <Step title="Set the alert rules">
    In **Alert rules**, choose any options for the alert type, such as which messaging events to watch. Then decide whether to [limit the alert to a SIM or tag](#limit-an-alert-to-a-sim-or-tag). With **Limit to SIM or tag** off, the alert is sent for every SIM in your organization.
  </Step>

  <Step title="Optionally, tag matching events">
    In **Modify event**, turn on **Add custom tag** to add your own identifier to events this alert matches. See [Add a custom tag](#add-a-custom-tag).
  </Step>

  <Step title="Choose how to be notified">
    In **Notification**, choose **Email** or **Webhook** and fill in the details. See [Notification methods](#notification-methods).
  </Step>

  <Step title="Save the alert">
    Review the preview at the top of the form, which summarizes the event, scope, and notification, then click **Save**. Click **Back** to choose a different alert type.
  </Step>
</Steps>

## Alert types

| Alert type | Triggered when | Event tags | Learn more |
| - | - | - | - |
| **Data limit reached and SIM paused** | A SIM reaches its data limit after its current data session closes, and is paused. | `_DATALIMIT_` | [Set usage limits](/dashboard/sim-actions/set-usage-limits) |
| **Data warning threshold reached** | A SIM crosses its data warning threshold after its current data session closes. | `_DATAWARNING_` | [Set a data warning threshold](/dashboard/sim-actions/set-data-warning-threshold) |
| **First IMEI recognized** | IMEI data for a SIM is returned in a closed session for the first time. | `_IMEI_FIRST_` | |
| **Hardware change (IMEI or TAC changed)** | A session reports a different IMEI, or a different IMEI TAC (modem model), than the SIM's last known IMEI. | `_IMEI_CHANGE_`, `_IMEI_TAC_CHANGE_` | |
| **Fallback event or profile change** | A SIM's enabled profile changes. | `_PROFILE_CHANGE_FALLBACK_`, `_PROFILE_CHANGE_MANUAL_`, `_PROFILE_CHANGE_SYSTEM_`, `_PROFILE_CHANGE_CONDUCTOR_` | [Fallback events](/guides/sims/fallback-events), [Switch profiles](/dashboard/sim-actions/switch-profiles) |
| **SMS/TCP/UDP message** | A message is sent to or from a SIM. | `_SMS_DO_`, `_SMS_DT_`, `_SMS_DT_DELIVERED_`, `_API_DT_` | [Send messages to SIMs](/dashboard/sim-actions/send-messages-to-sims) |
| **API responds to messaging attempt** | The API responds to an inbound or outbound message, for example when a message fails to deliver. | `_API_RESP_` | [Troubleshooting alerts and webhooks](/guides/troubleshooting/troubleshooting-alerts-and-webhooks) |
| **Conductor configuration change** | Conductor finished a step of a SIM or profile configuration change. One event is created for each step. | `_EUICC_CONFIGURE_SIM_` | [Conductor](/guides/sims/conductor) |
| **Any event for a specific SIM or tag** | Any event is generated for the SIMs or tag you choose. This can send a high volume of notifications. | `_DEVICE_XXX_` or `_TAG_XXX_` | [Generic event tags](/guides/cloud-and-tools/event-types-and-tags#generic-event-tags) |

<Note>
  **Note:** **Conductor configuration change** and the Conductor profile change option appear only for organizations with Conductor.
</Note>

### Alert type options

Some alert types let you narrow which events trigger the alert:

<AccordionGroup>
  <Accordion title="Hardware change">
    Under **IMEI to check**, choose **IMEI change**, **IMEI TAC change**, or both. A TAC change means the SIM is likely in a different model of modem, and is always accompanied by an IMEI change.
  </Accordion>

  <Accordion title="Fallback event or profile change">
    Under **Profile change type**, choose one:

    * **Fallback event**: the SIM fell back to another profile after losing connectivity, using Outage Protection™.
    * **Manual profile change**: a user switched the enabled profile.
    * **System profile change**: a Hologram system process, such as a migration, switched the enabled profile.
    * **Conductor profile change**: a Conductor configuration switched the enabled profile.

    To be notified about more than one type, create an alert for each.
  </Accordion>

  <Accordion title="SMS/TCP/UDP message">
    Choose one of **Outbound SMS** (sent from the SIM), **Inbound SMS** (sent to the SIM), **Inbound SMS delivered**, and **Inbound message** (TCP/UDP sent to the SIM).
  </Accordion>
</AccordionGroup>

## Limit an alert to a SIM or tag

By default, an alert is sent for every SIM in your organization. Turn on **Limit to SIM or tag** to narrow it:

* **Add SIM by device ID** limits the alert to one SIM. You can find a SIM's device ID on its **Status** and **Device** tabs.
* **Add tag** limits the alert to every SIM with that tag when the event occurs.

An alert can be limited to one SIM or one tag. To watch a group of SIMs with one alert, tag them and limit the alert to that tag. Behind the scenes, this adds a `_DEVICE_XXX_` or `_TAG_XXX_` event tag to the alert, and the alert only triggers for events that carry every tag on it.

## Add a custom tag

Turn on **Add custom tag** in **Modify event** to add your own identifier to events that match the alert, such as a customer or project code. Custom tags can't begin or end with an underscore, which is reserved for system tags.

## Notification methods

Every alert sends either an email or a webhook. Both support [event variables](/guides/cloud-and-tools/use-event-variables-in-alerts) to customize what's sent.

### Email

| Field | Description |
| - | - |
| **Recipients** | One or more email addresses, separated by commas. |
| **Subject** | The email subject line. You can include variables, such as `<<device.name>>`. |
| **Email message** | The body of the email. Defaults to `<<decdata>>`, the decoded contents of the event. Use variables to add details like the SIM name or data usage. |

### Webhook

| Field | Description |
| - | - |
| **Destination URL** | The `http` or `https` URL that receives a `POST` request. You can include variables to pass data as query string parameters. |
| **Message payload for POST** | The request body. Use variables to build the payload your service expects. JSON payloads are validated before you can save. |
| **Headers for POST** | Optional headers, such as an `Authorization` header from **Add basic auth header**, or a JSON content-type header. |

See [Webhook configuration](/guides/cloud-and-tools/event-monitoring-and-alerts-overview#webhook-configuration) for header and payload details, and [Troubleshooting alerts and webhooks](/guides/troubleshooting/troubleshooting-alerts-and-webhooks) if notifications don't arrive.

## Manage existing alerts

All of your organization's alerts are listed on the **Alerts** page. Each alert shows its event type, scope, and notification method, and a **Status** switch to turn it on or off without deleting it. A SIM's **Alerts** tab lists the alerts that apply to it, including global alerts and alerts for its tags.

Alerts created with older event types that are no longer supported are marked with a warning. See [Why does my alert say "No longer supported"?](/guides/cloud-and-tools/event-monitoring-and-alerts-overview#why-does-my-alert-say-no-longer-supported). This includes Socket API events, events with custom tags, heartbeat events, and deprecated notification methods.

## Recommended data usage alerts

If your organization uses data limits or data warning thresholds, we recommend creating a global alert for each. These recommendations will show up in both the organization and SIM alerts pages.

## Related guides

<Card title="About alerts and event monitoring" href="/guides/cloud-and-tools/event-monitoring-and-alerts-overview" icon="bell" horizontal>
  How alerts work, and the notification methods they support.
</Card>

<Card title="Event types and tags" href="/guides/cloud-and-tools/event-types-and-tags" icon="tag" horizontal>
  Every event tag, and the fields events contain.
</Card>

<Card title="Use variables from events in alerts" href="/guides/cloud-and-tools/use-event-variables-in-alerts" icon="brackets-curly" horizontal>
  Customize email and webhook contents with data from the event.
</Card>

<Card title="Forward messages to email with an alert" href="/guides/cloud-and-tools/create-a-notification-for-events-using-alerts" icon="envelope" horizontal>
  A step-by-step example.
</Card>

<Info>
  **Limited access:** Some functionality in your dashboard is restricted to [roles with access](/dashboard/orgs-and-users/user-roles).
</Info>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.