# Trigger configuration

Triggers can alert you by email, webhook, or push notification when any of the following events occur:

- [Machine telemetry data syncs from your local device to the Viam cloud](https://docs.viam.com/monitor/alert/)
- [Data syncs from a machine](https://docs.viam.com/data/trigger-on-data/)
- [A vision service detects a specified object or classifies a specified label](https://docs.viam.com/vision/object-detection/alert-on-detections/)
- [Machine logs contain errors, warnings, or info logs](https://docs.viam.com/monitor/alert/)

This page provides a reference for the Trigger attributes. For step-by-step configuration information, see the preceding links instead.

## JSON configuration templates

### Part status trigger template

The following template demonstrates the structure of a JSON configuration for a trigger that alerts when a part is online or offline:

```json

```

Part status triggers fire on every state transition. Viam sends a notification each time the part comes online or goes offline.

### Data sync trigger template

The following template demonstrates the structure of a JSON configuration for a trigger that alerts when data syncs to the Viam cloud:

```json

```

### Conditional trigger template

The following template demonstrates the structure of a JSON configuration for a conditional trigger:

```json

```

### Machine logs trigger template

```json

```

## Trigger attributes

Triggers support the following attributes:

| Name | Type | Required? | Description |
| --- | --- | --- | --- |
| `name` | string | **Required** | The name of the trigger |
| `event` | object | **Required** | The trigger event object, which contains the following fields:<br>- `type`: The type of the event to trigger on. Options:<br>  - `part_data_ingested`: fire when data syncs<br>  - `conditional_data_ingested`: fire when data that meets a certain condition syncs<br>  - `part_online`: fire when the part is online<br>  - `part_offline`: fire when the part is offline<br>  - `conditional_logs_ingested`: check every hour and fire if logs of the specified log level are present<br>- `data_types`: Required with `type` `part_data_ingested`. An array of data types that trigger the event. Options: `binary`, `tabular`, `file`, `unspecified`.<br>- `conditional`: Required when `type` is `conditional_data_ingested`. For more information about this field, see [Conditional attributes](https://docs.viam.com/reference/triggers/#conditional-attributes).<br>- `log_levels`: Required when `type` is `conditional_logs_ingested`. An array of log levels. Options: `error`, `warn`, `info`. |
| `notifications` | object | **Required** | The notifications object, which contains the following fields:<br>- `type`: The type of the notification. Options: `webhook`, `email`, `push`<br>- `value`: The URL to send the request to, the email address to notify, or `all_machine_owners` to notify all machine owners.<br>- `seconds_between_notifications`: The interval between notifications in seconds. 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.<br>- `application`: Required when `type` is `push`. The application ID for push notifications. Use `com.viam.viammobile` for the Viam mobile app, or provide your own custom application ID. To use a custom application ID, you must first upload your Firebase credentials to Viam with the [`organizations firebase-config set`](https://docs.viam.com/cli/reference/#organizations-firebase-config-set) CLI command. For the full setup flow, see [Set up custom push notifications](https://docs.viam.com/monitor/custom-push-notifications/).<br>For more information on webhooks, see [Webhook attributes](https://docs.viam.com/reference/triggers/#webhook-attributes). For push notifications, the recipient specified in `value` must be a machine owner or operator, and the recipient must have accepted push notification permissions for the application. |
| `notes` | string | Optional | Descriptive text to document the purpose, configuration details, or other important information about this trigger. |

## Conditional attributes

The `conditional` object for the `conditional_data_ingested` trigger type includes the following attributes:

| Name | Type | Required? | Description |
| --- | --- | --- | --- |
| `data_capture_method` | string | **Required** | The method of data capture to trigger on.<br>Example: `sensor:<name-of-component>:Readings`. |
| `conditions` | object | Optional | Conditions that, when true, fire the trigger. Evaluated each time data syncs from the linked component. When this object is empty or not present, the trigger fires each time data syncs from the linked component.<br>Options:<br>- `evals`:<br>  - `operator`: Logical operator for the condition.<br>  - `value`: An object containing a single field and value. The field specifies the path, in the synced data, to the left operand of the conditional. For nested fields, use periods as separators or define the nested structure in JSON. The value specifies an object, string, boolean, regular expression, or integer used as a right operand in the conditional. |

The `operator` attribute supports the following values:

| Name | Description |
| --- | --- |
| `lt` | less than |
| `gt` | greater than |
| `lte` | less than or equal to |
| `gte` | greater than or equal to |
| `eq` | equal to |
| `neq` | not equal to |
| `regex` | matches regular expression |

### Example

The following condition defines a trigger that fires based on the value of the `cpu` field of synced data:

```json

```

The following sensor reading fires the trigger, since `80 > 50` is `true`:

```json

```

### Nested key example

The following condition defines a trigger that fires based on a value nested in the `coordinate.latitude` field of synced data:

```json

```

The following sensor reading fires the trigger, since `40 < 50` is `true`:

```json

```

## Webhook attributes

### Request types

When an event occurs, Viam sends an HTTP request to the URL you specified for the trigger:

| Trigger type | HTTP Method |
| --- | --- |
| `part_data_ingested` | POST |
| `conditional_data_ingested` | POST |
| `part_online` | GET |
| `part_offline` | GET |

### Headers

The request includes the following headers:

| Header Key | Description | Trigger types |
| --- | --- | --- |
| `Org-Id` | The ID of the organization that triggered the request. | all |
| `Organization-Name` | The name of the organization that triggered the request. | `part_online`, `part_offline` |
| `Location-Id` | The location of the machine that triggered the request. | all |
| `Location-Name` | The location of the machine that triggered the request. | `part_online`, `part_offline` |
| `Part-Id` | The part of the machine that triggered the request. | all |
| `Machine-Name` | The name of the machine that triggered the request. | `part_online`, `part_offline` |
| `Robot-Id` | The ID of the machine that triggered the request. | all |

### Body

The request body includes the following data:

| Data Key | Description | Trigger types |
| --- | --- | --- |
| `component_name` | The name of the component for which data was ingested. | `part_data_ingested`, `conditional_data_ingested` |
| `component_type` | The type of component for which data was ingested. | `part_data_ingested`, `conditional_data_ingested` |
| `method_name` | The name of the method from which data was ingested. | `part_data_ingested`, `conditional_data_ingested` |
| `min_time_received` | Indicates the earliest time a piece of data was received. | `part_data_ingested` |
| `max_time_received` | Indicates the latest time a piece of data was received. | `part_data_ingested` |
| `machine_name` | The name of the machine that triggered the request. | `part_data_ingested`, `conditional_data_ingested` |
| `location_name` | The location of the machine that triggered the request. | `part_data_ingested`, `conditional_data_ingested` |
| `org_name` | The name of the organization that triggered the request. | `part_data_ingested`, `conditional_data_ingested` |
| `file_id` | The ID of the file that was ingested. | `part_data_ingested` |
| `trigger_condition` | The condition that triggered the request. | `conditional_data_ingested` |
| `data` | The ingested sensor data. Includes `metadata` with `received_at` and `requested_at` timestamps and `data` in the form `map[string]any`. | `part_data_ingested`, `conditional_data_ingested` (sensor data) |

### Example cloud function

If you are using a cloud function or lambda to process the request from `viam-server`, you can use this template.

The following example function prints the received headers:

```python

```

### Troubleshooting

If the HTTP request Viam sends results in an error, you can see this error logged in the machine logs.

For example:

```txt
9/18/2025, 12:52:59 PM error app.trigger.trigger-1     Trigger failed to notify https://testurl.com for robotPartId abc1234d-1a23-1a23-123a-1abc23d45e67. Component: N/A, Method: N/A, TriggerType: part_online, NotificationType: webhook, Error: received unretryable status code: 404 in webhook response, ResponseCode: 404
```