Configure a Webhook

Webhooks allow you to trigger actions when certain types of data are sent from your machine to the cloud, or when the internet connectivity of your machine changes. For example, you can configure a webhook to send you a notification when your robot’s sensor collects a new reading. Viam provides two webhook 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 specified interval while the machine part is online
  • Part is offline: trigger continuously at specified interval while the machine part is offline

To configure a webhook:

  1. Go to the CONFIGURE tab of your machine on the Viam app. Click the + (Create) button in the left side menu and select Webhook.

    The Create menu with Webhook at the bottom of the list of options.
  2. Name the webhook and click Create.

  3. Select the type of event to trigger on from the Type dropdown.

  4. Follow the instructions depending on the type of webhook you want to implement:

  1. Select the types of data you want to trigger on from the dropdown. Whenever any data of the type you select is synced from any component on your machine, the webhook will trigger.
  1. While your part is online, the webhook action triggers at a specified interval. Edit the Time between notifications attribute to set this interval according to your preferences.
  1. While your part is offline, the webhook action triggers at a specified interval. Edit the Time between notifications attribute to set this interval according to your preferences.
  1. Replace the URL value with the URL of your cloud/lambda function.

    The webhook configured with an example URL in the Viam app.

If you prefer to configure your webhook with raw JSON instead of the config builder, you can paste one of the following JSON templates into your JSON config. "webhooks" is a top-level section like "components" or "services".

  "webhooks": [
    {
      "url": "<Insert your own cloud function or lambda URL for sending the event>",
      "event": {
        "type": "part_data_ingested",
        "attributes": {
          "data_types": ["binary", "tabular", "file"]
        }
      }
    }
  ]
  "webhooks": [
    {
      "url": "<Insert your own cloud function or lambda URL for sending the event>",
      "event": {
        "type": "part_online",
        "attributes": {
          "seconds_between_notifications": <number of seconds>
        }
      }
    }
  ]
  "webhooks": [
    {
      "url": "<Insert your own cloud function or lambda URL for sending the event>",
      "event": {
        "type": "part_offline",
        "attributes": {
          "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
              }
            ]
          }
        }
      ]
    }
  ],
  "webhooks": [
    {
      "url": "https://1abcde2ab3cd4efg5abcdefgh10zyxwv.lambda-url.us-east-1.on.aws",
      "event": {
        "type": "part_data_ingested",
        "attributes": {
          "data_types": ["binary", "tabular"]
        }
      }
    }
  ]
}
  1. Write your cloud/lambda function to process the request from viam-server. The following example function sends a Slack message with a machine’s details, such as robot and location IDs, when it receives a request:

    import functions_framework
    import requests
    import time
    
    @functions_framework.http
    def hello_http(request):
      payload = {
        "Org-ID": request.headers['org-id'] if 'org-id' in request.headers else 'no value',
        "Location-ID": request.headers['location-id'] if 'location-id' in request.headers else 'no value',
        "Part-ID": request.headers['part-id'] if 'part-id' in request.headers else 'no value',
        "Robot-ID": request.headers['robot-id'] if 'robot-id' in request.headers else 'no value'
      }
    
      slack_url = "<paste in your own Slack URL>"
      headers = {}
    
      response = requests.post(slack_url, json=payload, headers=headers)
    
      request_json = request.get_json(silent=True)
      request_args = request.args
    
      return 'Sent request to {}'.format(slack_url)
    

More examples

The Monitor Job Site Helmet Usage with Computer Vision tutorial uses webhooks to send email notifications.

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.