Custom Webhooks
Last updated
Last updated
This guide walks through how to create a custom webook for integrating the ThousandEyes platform with third-party services. For more in-depth documentation for particular services, see .
To create a new webhook, do the following:
In the ThousandEyes platform, go to Manage > Integrations.
Click + New Integration.
In the Add New Custom Integration panel, configure the fields for your new custom webhook:
Field
Description
Name
A name for your custom webhook.
We recommend you use a human-readable, meaningful string. If you create multiple webhooks, it’s a good practice to use a consistent naming convention.
URL
The target URL of the server associated with your webhook.
Note: HTTP redirects are not accepted. Make sure you provide the final URL in this field.
Preset Configurations
These optional preset configurations provide a starting place from which you can create your custom webhook. If you use a preset configuration, it populates the fields below with sample content that you can adapt.
Note: These preset configurations can serve as a guide, but you should verify that the resulting webhook’s structure and variables meet your requirements.
You can use any of the following preset configurations for your webhook:
Generic
AppDynamics
Cisco Webex
Microsoft Teams
Slack
Splunk
[additional preset configurations to come]
Caution: When you select a preset configuration, any settings you have already made in the fields below are deleted.
Auth Type
Set the authentication method for your webhook:
None
Basic
Token
OAuth
Headers
The Headers field contains key/value pairs that make up the webhook’s HTTP header to a server and that function as metadata for the webhook.
The key/value pairs you enter here can be static (a set key and its set value) or dynamic (a set key and a variable as its value)
To add additional key/value pairs to the header of your webhook, click + Key-Value Pair and enter the key and value.
To remove a key/value pair, click the - symbol.
URL Query Parameters
These parameters are appended to a URL to define content or actions, especially when integrating into a third-party system.
You can type directly into the text box to add URL query parameters to your webhook.
To see an expanded view of the contents of the field, click the arrows button.
Body
Define the body of your webhook to suit your needs. Note that the body
Must be valid JSON.
Can include static or dynamic key/value pairs. Variables must match Handlebars syntax.
You can type directly into the text box to customize the body of your webhook.
To see an expanded view of the contents of the field, click the arrows button.
[Optional] Click Test to test your new custom webhook.
For detailed information, see .
Click Save.
Your new webhook is listed at Manage > Integrations.
[Optional] Attach alert rules to your new webhook.
For detailed instructions, see .
The ThousandEyes webhook templates use the Handlebars templating language. In fact, in a custom webhook, the Body field is a Handlebars template.
When you edit the Headers, URL Query Parameters, and Body fields, the webhook editor UI automatically suggests variables that match the text you have written or that was present in the template.
For example, if you type “a” into the editor, it suggests “alerts” as a possible completion. Once a given variable is completed, the editor suggests sub-variables available for it. For example, if the variable completed is “alert.”, the editor suggests all possible sub-variables, such as “id” “rule," and “firstSeen." You can prompt the editor's suggestions manually by typing Ctrl+space.
In the ThousandEyes platform, go to Manage > Integrations.
In the list of your integrations, find the webhook you want to test.
The Status column shows whether the webhook has been tested.
Click the row for the webhook you want to test (or click its context menu and select Edit).
In the Edit panel, click Test.
If your test fails, use the error message as displayed in this panel to troubleshoot your configuration.
When you click Test, the following elements of your webhook’s configuration are tested:
The URL you have provided.
The authentication you have provided.
The format of the payload.
The ThousandEyes platform sends a dummy HTTP alert trigger to test the format of the payload as defined in your webhook. It evaluates the server’s response to determine whether the server can accept the payload.
At Manage > Integrations, your webhooks are listed, showing their test status. The Status field can have the following values:
Untested
This webhook has not been tested through the ThousandEyes platform.
Failure
This webhook has been tested through the ThousandEyes platform, but has failed this test.
If your webhook has a Failure status, it can still be attached to alert rules and might still be dispatched.
The Failure status typically means either that the server did not respond, or that the payload itself is malformed. However, in some cases these failures do not prevent the successful dispatch of a custom webhook.
Success
This webhook has been tested through the ThousandEyes platform, and has successfully dispatched a test payload.
However, note that in some cases a successful test does not guarantee the successful dispatch of a custom webhook attached to an alert rule.
In the ThousandEyes platform, go to Manage > Integrations.
In the list of your integrations, find the webhook you want to attach alert rules to.
From the ellipsis (...) dropdown at the right, select Manage Alert Rules.
In the Manage Alert Rules panel, select the alert rule or rules that should be associated with this webhook.
If you have a large number of alert rules, use the Search box to filter on a relevant string. You can also sort alert rules by name and by alert type.
Click Save.
If alert notifications fail to be sent via custom webhooks, we continuously retry sending the notification for up to two hours after the first failure. We retry up to nine times at the following intervals (in minutes) after the first failure:
These intervals map to the following minutes after the first failure:
If after this time the notification still isn't sent, the notification is dropped.
In the ThousandEyes platform, go to Manage > Integrations.
In the list of integrations, find the webhook you want to edit.
Click the row for the webhook you want to edit (or click its ellipsis (...) menu and select Edit).
In the Edit panel, make your changes.
[Optional] Click Test to test your updated custom webhook.
Click Save.
In the ThousandEyes platform, go to Manage > Integrations.
In the list of integrations, find the webhook you want to duplicate.
From its ellipsis (...) menu, select Duplicate.
The system creates a new webhook that has:
The name of the previous webhook, with the string copy appended to it.
The same configuration as the previous webhook.
No alert rules attached to it.
[Optional] Click Test to test your updated custom webhook.
Click Save.
[Optional] Attach alert rules to your new webhook.
In the ThousandEyes platform, go to Manage > Integrations.
In the list of integrations, select the webhook you want to delete.
From the ellipsis (...) menu, select Delete.
Note: Deleting a webhook removes it from any alert rules that were attached to it. Deleted webhooks can be manually re-created, but cannot be restored.
If your web server only allows requests from allowlisted senders, you will need to allow requests from ThousandEyes web servers, which come from the following IP addresses, which are region-specific:
US1 Region
US2 Region
EU1 Region
If you’re encountering issues with your custom webhook, consider the following points:
A common way a webhook might fail despite passing testing is when conditional Handlebars helpers are used. For example, the template might contain a clause like the following:
"timeTriggered": {{#eq type 2 }} {{ alert.firstSeen.epochSecond }} {{/eq}}
If the underlying alert’s state is triggered, as it is in the sample we use when we test a webhook, this syntax renders correctly. But if the alert’s state is cleared, this syntax fails due to being invalid JSON: the “timeTriggered” key in the resulting object will have no value.
Watch for illegal characters in the underlying alert data, particularly for custom headers. We apply URL escaping to query parameters, but not to the webhook's header or payload.
Do not use # for custom helpers like formatDate or formatExpression.
For basic and token authentication, see .
For OAuth, see .
For guidance on defining query parameters, see.
For guidance on the editor for the Body field, see .
For convenience, the variables and some guidance on using them are available in .
When you write your own webhook, the syntax in the Body field must conform to the Handlebars syntax rules. For detailed information on the Handlebars language, see the .
It’s a good practice to test your webhooks before deploying them. You can test a webhook , or after you have saved it:
Once you have and , you’ll attach to it so that ThousandEyes alert notifications can flow into the system you’ve integrated with.
For a detailed description of the fields in this panel, see .
For detailed instructions, see .
For more information about regions, see .