Configure a Trigger
Triggers allow you to trigger webhooks when certain types of data are sent from your machine to the cloud, or when the your machine parts connect to Viam. For example, you can configure a trigger to send you a notification when your robot’s sensor collects a new reading. Viam provides three trigger types depending on the event you want to trigger on:
- Data has been synced to the cloud: trigger when data from the machine is synced
- Part is online: trigger continuously at a specified interval while the machine part is online
- Part is offline: trigger continuously at a specified interval while the machine part is offline
To configure a trigger:
Go to the CONFIGURE tab of your machine on the Viam app. Click the + (Create) button in the left side menu and select Trigger.
Name the trigger and click Create.
Select trigger Type. For the respective type, configure the respective attributes:
Select the data types for which the Trigger should send requests.
Whenever data of the specified data types is ingested, a POST request will be sent.
- Add Webhooks or Emails.
Replace the URL value with the URL of your cloud function or lambda. Configure the time between notifications.
Add the email you wish to be notified whenever this trigger is triggered. Configure the time between notifications.
To configure your trigger by using JSON mode instead of Builder mode, paste one of the following JSON templates into your JSON config.
"triggers" is a top-level section, similar to "components" or "services".
"triggers": [
{
"name": "<trigger name>",
"event": {
"type": "part_data_ingested",
"data_ingested": {
"data_types": ["binary", "tabular", "file"]
}
},
"notifications": [
{
"type": "webhook",
"value": "https://1abcde2ab3cd4efg5abcdefgh10zyxwv.lambda-url.us-east-1.on.aws",
"seconds_between_notifications": <number of seconds>
}
]
}
]
"triggers": [
{
"name": "<trigger name>",
"event": {
"type": "part_online"
},
"notifications": [
{
"type": "webhook",
"value": "<https://1abcde2ab3cd4efg5abcdefgh10zyxwv.lambda-url.us-east-1.on.aws>",
"seconds_between_notifications": <number of seconds>
}
]
}
]
"triggers": [
{
"name": "<trigger name>",
"event": {
"type": "part_offline"
},
"notifications": [
{
"type": "webhook",
"value": "<https://1abcde2ab3cd4efg5abcdefgh10zyxwv.lambda-url.us-east-1.on.aws>",
"seconds_between_notifications": <number of seconds>
}
]
}
]
{
"components": [
{
"name": "local",
"model": "pi",
"type": "board",
"namespace": "rdk",
"attributes": {},
"depends_on": []
},
{
"name": "my_temp_sensor",
"model": "bme280",
"type": "sensor",
"namespace": "rdk",
"attributes": {},
"depends_on": [],
"service_configs": [
{
"type": "data_manager",
"attributes": {
"capture_methods": [
{
"method": "Readings",
"additional_params": {},
"capture_frequency_hz": 0.017
}
]
}
}
]
}
],
"triggers": [
{
"name": "trigger-1",
"event": {
"type": "part_data_ingested",
"data_ingested": {
"data_types": ["binary", "tabular", "file"]
}
},
"notifications": [
{
"type": "webhook",
"value": "<https://1abcde2ab3cd4efg5abcdefgh10zyxwv.lambda-url.us-east-1.on.aws>",
"seconds_between_notifications": 0
}
]
}
]
}
The following attributes are available for triggers:
| Name | Type | Required? | Description |
|---|---|---|---|
name | string | Required | The name of the trigger |
event | object | Required | The trigger event object:
|
notifications | object | Required | The notifications object:
|
Write your cloud function or lambda to process the request from
viam-server. You can use your cloud function or lambda to interact with any external API such as, for example, Twilio, PagerDuty, or Zapier. 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'), "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'), "Data": data.get('data', 'no value') } print(payload) return 'Received headers: {}'.format(payload)
Returned headers
When a trigger occurs, Viam sends a HTTP request to the URL you specified for the trigger:
| Trigger type | HTTP Method |
|---|---|
part_data_ingested | POST |
part_online | GET |
part_offline | GET |
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 |
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 |
component_type | The type of component for which data was ingested. | part_data_ingested |
method_name | The name of the method from which data was ingested. | part_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 |
location_name | The location of the machine that triggered the request. | part_data_ingested |
org_name | The name of the organization that triggered the request. | part_data_ingested |
file_id | The id of the file that was ingested. | part_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 (sensor data) |
Next steps
To see an example project that uses triggers to send email notification, see the Monitor Job Site Helmet Usage with Computer Vision tutorial.
Have questions, or want to meet other people working on robots? Join our Community Discord.
If you notice any issues with the documentation, feel free to file an issue or edit this file.
Was this page helpful?
Glad to hear it! If you have any other feedback please let us know:
We're sorry about that. To help us improve, please tell us what we can do better:
Thank you!