# Trigger on data events

Get alerted when your robot’s data meets a condition. Triggers send webhooks, email notifications, or push notifications to a mobile app when events occur on a machine, so you can respond to temperature spikes, low battery, detection results, or connectivity changes without polling.

Triggers are configured in the machine’s config and are scoped to that machine. Each trigger fires when its event occurs on the specific machine it is configured on.

## Trigger types

Viam supports five trigger types:

| Type | Event JSON value | Fires when |
| --- | --- | --- |
| Data synced | `part_data_ingested` | Any data syncs from the machine to the cloud. |
| Conditional data ingestion | `conditional_data_ingested` | Synced data meets a specified condition (key, operator, value). |
| Part online | `part_online` | The machine part comes online. |
| Part offline | `part_offline` | The machine part goes offline. |
| Conditional logs ingestion | `conditional_logs_ingested` | Machine logs contain errors, warnings, or info messages (checked hourly). |

For the full attribute reference for all trigger types, see [Trigger configuration](https://docs.viam.com/reference/triggers/).

## Configure a trigger

1. Go to the **CONFIGURE** tab of your machine. Click the **+** (Create) button in the left side menu and select **Trigger**.

2. Enter a name and click **Create**.

3. In the **Type** dropdown, choose one of the following event types:

- **Data has been synced to the cloud**: Whenever your machine syncs data of any of the specified data types, the trigger fires. Then select the data types for which the trigger should send requests.

- **Conditional data ingestion**: Whenever your machine syncs data that meets certain criteria, the trigger fires.

1. Choose the target component and method for your condition.

2. Add a **condition**: specify a **key** in the synced data, an **operator**, and a **value**. When data from the target component and method syncs from your machine, the trigger uses the key as a path to look up a value in the synced data object. The trigger applies the operator to the extracted value and the value you specified in your condition.
        
        For example, the following trigger sends an alert when the `cpu-monitor` component’s `Readings` method syncs `cpu` usage greater than `50`:
        
        To see the data your components are returning, use each component’s **TEST** panel.
        
        For a full reference of trigger configuration attributes, see [Trigger configuration](https://docs.viam.com/reference/triggers/).

4. Next, configure what should happen when an event occurs. You can add **Webhook**, **Email**, and **Push** notifications:

To add a webhook:

1. Click **Add webhook**.
2. Add the URL of your cloud function.
3. Configure the time between notifications.
4. Write your cloud function to process the webhook payload. Use your cloud function to process data or interact with external APIs, such as Twilio, PagerDuty, or Zapier.

To add an email notification for specific email addresses:

1. Toggle **Email specific addresses** on and add the email addresses you wish to be notified whenever this trigger fires.
2. Set the alert frequency (minimum time between notifications).

To add an email notification for all machine owners:

1. Toggle **Email all machine owners** on.
2. Set the alert frequency (minimum time between notifications).

To add a push notification:

1. Click **Add push notifications**.
2. Choose the target mobile app (Viam mobile or a custom app ID).
3. Add specific email addresses of recipients who should receive push notifications, or toggle on notifications for all machine owners. Recipients must be machine owners or operators.
4. Set the alert frequency (minimum time between notifications).

For end-to-end setup of a custom application ID (Firebase upload, device registration, machine authorization), see [Set up custom push notifications](https://docs.viam.com/monitor/custom-push-notifications/).

The following JSON configuration shows how to set up a trigger that fires when any data is synced to the cloud:

```json

```

For more information about triggers, see [Trigger Configuration](https://docs.viam.com/reference/triggers/).

## Webhook payload

When a trigger fires and sends a webhook, the HTTP request includes identifying headers (`Org-Id`, `Location-Id`, `Part-Id`, `Robot-Id`) and a JSON body with details about the event. For data triggers (`part_data_ingested`, `conditional_data_ingested`), the body includes the component name, method, timestamps, and the ingested data. For status triggers (`part_online`, `part_offline`), the request is a GET with metadata in headers only.

For the full header and body reference, see [Webhook attributes](https://docs.viam.com/reference/triggers/#webhook-attributes). For example cloud functions that process the payload, see [Example cloud function](https://docs.viam.com/reference/triggers/#example-cloud-function).

## Notification interval

The `seconds_between_notifications` field sets the minimum time between notifications for data triggers (`part_data_ingested` and `conditional_data_ingested`). If a trigger fires more frequently than this interval, additional notifications are suppressed until the interval has elapsed. To avoid floods of notifications, set the interval to a value appropriate for your use case (for example, 3600 to allow at most one alert per hour).

This field is ignored for `part_online` and `part_offline` triggers, which fire on every state transition. It is also ignored for `conditional_logs_ingested` triggers, where the check interval is always one hour.

## Machine telemetry triggers

The **Part online**, **Part offline**, and **Conditional logs ingestion** triggers are primarily used for machine health monitoring rather than data analysis. For step-by-step setup of these trigger types, see [Alert on machine telemetry](https://docs.viam.com/monitor/alert/).

For the full attribute reference for all trigger types, see [Trigger configuration](https://docs.viam.com/reference/triggers/).