Trigger configuration | Viam Documentation

Trigger configuration

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

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:

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:

Conditional trigger template

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

Machine logs trigger template

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:
- type: The type of the event to trigger on. Options:
- part_data_ingested: fire when data syncs
- conditional_data_ingested: fire when data that meets a certain condition syncs
- part_online: fire when the part is online
- part_offline: fire when the part is offline
- conditional_logs_ingested: check every hour and fire if logs of the specified log level are present
- data_types: Required with type part_data_ingested. An array of data types that trigger the event. Options: binary, tabular, file, unspecified.
- conditional: Required when type is conditional_data_ingested. For more information about this field, see Conditional attributes.
- 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:
- type: The type of the notification. Options: webhook, email, push
- value: The URL to send the request to, the email address to notify, or all_machine_owners to notify all machine owners.
- 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.
- 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 CLI command. For the full setup flow, see Set up custom push notifications.
For more information on webhooks, see 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.
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.
Options:
- evals:
- operator: Logical operator for the condition.
- 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:

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

Nested key example

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

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

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:

Troubleshooting

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

For example:

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