Reference: Trigger configuration

Mon, 05 May 2025 00:00:00 +0000

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:

"triggers": [
{
"name": "<trigger name>",
"event": {
"type": "part_online|part_offline"
},
"notifications": [
{
"type": "<webhook|email|push>",
"value": "<webhook URL, email address, or all_machine_owners>",
"seconds_between_notifications": <number of seconds>
}
]
}
]

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:

"triggers": [
{
"name": "<trigger name>",
"event": {
"type": "part_data_ingested",
"data_ingested": {
"data_types": ["binary", "tabular", "file", "unspecified"]
}
},
"notifications": [
{
"type": "<webhook|email|push>",
"value": "<webhook URL, email address, or all_machine_owners>",
"seconds_between_notifications": <number of seconds>
}
]
}
]

Conditional trigger template

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

"triggers": [
{
"name": "<trigger name>",
"event": {
"type": "conditional_data_ingested",
"conditional": {
"data_capture_method": "<component>:<name-of-component>:<method>",
"conditions": {
"evals": [
{
"operator": "<lt|gt|lte|gte|eq|neq|regex>",
"value": <object, string, bool, regex, or int>
}
]
}
}
},
"notifications": [
{
"type": "<webhook|email>",
"value": "<webhook URL or email address or all_machine_owners>",
"seconds_between_notifications": <number of seconds>
}
]
}
]

Machine logs trigger template

"triggers": [
{
"name": "<trigger name>",
"event": {
"type": "conditional_logs_ingested",
"log_levels": [
"error",
"warn",
"info"
]
},
"notifications": [
{
"type": "<webhook|email>",
"value": "<webhook URL or email address or all_machine_owners>"
}
]
}
]

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 event type `conditional_logs_ingested` where the 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 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:

"conditions": {
"evals": [
{
"operator": "gt",
"value": {
"cpu": 50
}
}
]
}

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

{
"readings": {
"cpu": 80
}
}

Nested key example

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

"conditions": {
"evals": [
{
"operator": "lt",
"value": {
"coordinate": {
"latitude": 50
}
}
}
]
}

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

{
"readings": {
"coordinate": {
"latitude": 40
}
}
}

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:

Flask:

from flask import Flask, request
app = Flask(__name__)
@app.route("/", methods=['GET', 'POST'])
def trigger():
headers = request.headers
data = {}
if request.data:
data = request.json
# For logs the return type is an array
if isinstance(data, list):
data = {"logs": data}
payload = {
"Org-Id": headers.get('org-id', 'no value'),
"Organization-Name": headers.get('organization-name', '') or
data.get('org_name', 'no value'),
"Location-Id": headers.get('location-id', 'no value'),
"Location-Name": headers.get('location-name', '') or
data.get('location_name', 'no value'),
"Part-Id": headers.get('part-id', 'no value'),
"Part-Name": headers.get('part-name', 'no value'),
"Robot-Id": headers.get('robot-id', 'no value'),
"Machine-Name": headers.get('machine-name', '') or
data.get('machine_name', 'no value'),
"Component-Type": data.get('component_type', 'no value'),
"Component-Name": data.get('component_name', 'no value'),
"Method-Name": data.get('method_name', 'no value'),
"Min-Time-Received": data.get('min_time_received', 'no value'),
"Max-Time-Received": data.get('max_time_received', 'no value'),
"Data-Type": data.get('data_type', 'no value'),
"File-Id": data.get('file_id', 'no value'),
"Trigger-Condition": data.get("trigger_condition", 'no value'),
"Data": data.get('data', 'no value'),
"Logs": data.get('logs', 'no value')
}
print(payload)
return payload
if __name__ == '__main__':
app.run(host='0.0.0.0', port=8080)

functions_framework:

import functions_framework
import requests
import time
@functions_framework.http
def hello_http(request):
headers = request.headers
data = {}
if request.data:
data = request.json
# For logs the return type is an array
if isinstance(data, list):
data = {"logs": data}
payload = {
"Org-Id": headers.get("org-id", "no value"),
"Organization-Name": headers.get("organization-name", "")
or data.get("org_name", "no value"),
"Location-Id": headers.get("location-id", "no value"),
"Location-Name": headers.get("location-name", "")
or data.get("location_name", "no value"),
"Part-Id": headers.get("part-id", "no value"),
"Part-Name": headers.get("part-name", "no value"),
"Robot-Id": headers.get("robot-id", "no value"),
"Machine-Name": headers.get("machine-name", "")
or data.get("machine_name", "no value"),
"Component-Type": data.get("component_type", "no value"),
"Component-Name": data.get("component_name", "no value"),
"Method-Name": data.get("method_name", "no value"),
"Min-Time-Received": data.get("min_time_received", "no value"),
"Max-Time-Received": data.get("max_time_received", "no value"),
"Data-Type": data.get("data_type", "no value"),
"File-Id": data.get('file_id', "no value"),
"Trigger-Condition": data.get("trigger_condition", "no value"),
"Data": data.get('data', 'no value'),
"Logs": data.get('logs', 'no value')
}
print(payload)
return 'Received headers: {}'.format(payload)

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

Viam Documentation – Push Notification