Trigger configuration

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

• machine telemetry data syncs from your local device to the Viam cloud
• data syncs from a machine
• service detects a specified object or classifies a specified label

This page provides a reference for the Trigger attributes. For step-by-step configuration information, see the links above 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",
        "value": "<webhook URL or email address>",
        "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>",
          "value": "<webhook URL or email address>",
          "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>",
          "seconds_between_notifications": <number of seconds>
        }
      ]
    }
]

Trigger attributes

Triggers support the following attributes:

Conditional attributes

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

The operator attribute supports the following values:

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:

Headers

The request includes the following headers:

Body

The request body includes the following 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:

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
    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')
    }
    print(payload)

    return payload


if __name__ == '__main__':
    app.run(host='0.0.0.0', port=8080)

import functions_framework
import requests
import time


@functions_framework.http
def hello_http(request):
    headers = request.headers
    data = {}
    if request.data:
        data = request.json
    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")
    }
    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