ThousandEyes Alerts – API and Webhooks


There are a few different ways of handling ThousandEyes alerts. Active alerts can be polled via the API, forwarded by email, sent to PagerDuty or via webhook. I will be covering alerting via API and notifications via webhooks.


Accessing the alerts API is simple. Examples from my previous post on the ThousandEyes API are relevant. Here is Python code to query and “pretty print” active alerts in json format:

By default only active alerts are returned. In order to pull back previous alerts, time ranges should be used. These are also referenced in the alerts API documenation. I will append ?window=5d in order to return active alerts:

Output (removed all but one test location):


Webhooks are configured via the Alerts page. You provide a name and a URL, optionally providing basic HTTP authentication. You should use authentication and SSL/TLS to avoid sending the traffic in the clear.



Here is a simple webhook handler in Python. It does not include SSL/TLS or authentication and I would not use this for anything other than simple testing.

An event notification message is sent when an alert is triggered and a notification is sent when the condition has cleared.


I have covered how to pull back alert information via both the ThousandEyes API and receiving alerts via Webhooks. The next step would be to perform some sort of integration with a logging, management or ticketing system.

Accessing the ThousandEyes API

The ThousandEyes API is very well documented. The examples in the documentation show the request/response transactions using curl. I will be writing my API calls with Python so they can be accessed and post-processed easily. I will be using the requests and json Python modules.

Here is the “Hello World” of requesting API data and saving it as json:


The API uses HTTP Basic authentication to access your account. The username is your account login and the password is the user token which can be found in your user settings. To test access to my account, I am going to pull back a list of tests.


I currently have one test created, so the API response contains information about that test. You can see that the response data contains API links to test data. In order to programmatically access the response data, you can treat the json object as a Python dictionary. For instance, to return the API link for BGP test data you would access j['test'][0]['apiLinks'][4]['href']: ''. This link will return the BGP metrics from the test.

This post has gone over accessing the ThousandEyes API. In my next post I will review additional API functionality.