Cisco Webex for Alert Notifications

This article shows you how to send ThousandEyes alert notifications to a Cisco Webex App space by using a custom webhook operation.

Complete the following steps in order.

Before You Begin

Requirement	Details
Webex account	Access to Webex for Developers and membership in the destination Webex App space.
Webex App space	The destination for ThousandEyes alert notifications. You can create the space during this procedure.
ThousandEyes access	Access to Manage > Integrations in the ThousandEyes platform.
Webex credential	A Webex bot access token. Personal access tokens are for testing only, expire after 12 hours, and are not intended for production integrations. See Personal Access Token.

Creating a Webex Bot and Finding the Space ID

1. In Webex for Developers, create a Webex bot.

   • Log in to Webex for Developers.

   • Open the menu under your avatar and select My Webex Apps > Create a New App > Create a Bot.

   • Enter the bot settings:

     Field	Value
     Bot name	A descriptive name, preferably without spaces, such as ThousandEyesAlerts
     Bot username	A username that is unique in Webex
     Icon	A Webex icon or your own bot icon
     App Hub Description	Simple bot that sends ThousandEyes alerts to Webex through a webhook

   • Select Add Bot.

   Result: Webex opens a confirmation screen with the bot details and access token. See Creating a Webex Bot for current Webex field requirements.

2. Copy the bot access token.

   • Copy the token from the confirmation screen. Webex displays it only once.

   • Store the token securely. You use it as the bearer token in ThousandEyes.

   • If you lose the token, open the bot from My Webex Apps and select Regenerate Access Token.

   Result: You have the bot credential required for the custom webhook connector.

3. In Webex App, create or choose the space that receives ThousandEyes alert notifications.

   Situation	Action
   You have a destination space	Open the space and continue to step 4.
   You need a destination space	Select the add button at the top of the spaces list, select Create a Space, enter a name such as ThousandEyes-Webhook-Test, and select Create.

   See Webex App | Create a Space for instructions for desktop, web, and mobile apps.

4. Add the Webex bot to the space.

   • In Messaging, open the destination space.

   • Select People > Add people.

   • Search for the bot by its name or username.

   • Select the bot and select Add.

   Result: The bot appears in the space's people list and can post messages to the space. See Webex App | Add People to a Space for platform-specific instructions.

5. Copy the space's roomId.

   • Open the Webex List Rooms API reference and log in.

   • Enable Try It and run the request.

   • In the items array, find the object whose title matches your Webex App space.

   • Copy that object's id. Webex App calls the destination a space, but the Webex API uses /rooms and roomId.

   The sample space appears in the response as follows. The response also contains other fields.

   {
      "items": [
         {
            "id": "<roomId>",
            "title": "ThousandEyes-Webhook-Test"
         }
      ]
   }

   Result: You have the roomId required for the custom webhook body.

Creating the Custom Webhook Connector

1. In the ThousandEyes platform, select Manage > Integrations > Integrations 2.0.

2. On the Integration Templates tab, select Custom Webhook.

3. Configure the connector fields.

   Field	Value
   Name	A descriptive name, such as Webex App Alerts
   Target	https://webexapis.com
   Auth Type	Bearer Token
   Bearer Token	The Webex bot access token

   Result: The connector contains the Webex API host and bot credential.

4. Select Save & Assign Operation.

   Result: ThousandEyes saves the connector and opens the custom webhook operation settings.

Creating the Custom Webhook Operation

1. In Preset Configurations, select Cisco Webex.

   The preset adds	Configure separately
   Starting JSON body	Connector: Webex target and bot access token
   Content-Type: application/json header	Operation: Path and Webex roomId

   

   Cisco Webex preset selected in the custom webhook operation
2. Configure the operation fields.

   Field	Value
   Operation Name	A descriptive name, such as Send alerts to Webex
   Path	/v1/messages
   Headers	Content-Type set to application/json
   Body	The JSON body in step 12

   Result: The connector target and operation path call the Webex Create a Message API at https://webexapis.com/v1/messages.

3. Replace the preset body with the following JSON, then replace <roomId> with the value copied in step 5.

   This integration sends a plain markdown message. The account ID in the alert link is added from the alert data.

   {
      "roomId" : "<roomId>",
      "markdown" : "<strong>ThousandEyes Alert{{#eq type.id 2}} Triggered{{else}} Cleared{{/eq}}{{#if alert.test}} for {{alert.test.name}}{{/if}}</strong>\n<strong>Alert ID:</strong> {{alert.id}}{{#if alert.test}}\n<strong>Test Name:</strong> {{alert.test.name}}\n<strong>Target/s:</strong> {{#each alert.targets}}{{description}}{{#unless @last}} {{/unless}}{{/each}}{{/if}}\n<strong>Alert Rule:</strong> {{alert.rule.name}} - {{formatExpression alert.rule.expression}}{{#if alert.details}}\n<strong>Details:</strong> {{alert.details.size}}{{/if}}\n<strong>Severity:</strong> {{alert.severity.display}}\n<strong>Alerts Link:</strong> https://app.thousandeyes.com/alerts/list?__a={{alert.rule.account.id}}&alertId={{alert.id}}"
   }

4. Validate the final JSON before you test or save the operation.

   • Confirm that the body is valid JSON.

   • Confirm that roomId contains the ID copied in step 5.

   • Confirm that the Handlebars variables use supported syntax. See Webhook Variables.

Testing the Integration

1. In the custom webhook operation, select Test.

   

   Custom webhook test success message
2. Verify that the sample test message appears in the Webex App space.

   Verify the following items:

   • The message appears in the intended Webex App space.

   • The bot is the message sender.

   • The heading shows the ThousandEyes alert state and test name.

   • The message contains the alert ID, target, alert rule, severity, and alert link.

   • The message contains alert details when they are available.

   The Webex Create a Message API defines the roomId and markdown fields. The current ThousandEyes sample alert generates these values:

   Message field	Sample value
   Heading	ThousandEyes Alert Triggered for Sample Test
   Alert ID	0
   Test Name	Sample Test
   Target/s	Sample Target
   Alert Rule	Sample Rule - Response Time ≥ 111 ms
   Details	2
   Severity	Info
   Alerts Link	https://app.thousandeyes.com/alerts/list?__a=0&alertId=0

3. Select Save Integration.

   Result: ThousandEyes saves the connector and custom webhook operation.

4. Assign the custom webhook operation to the alert rules that should send notifications to Webex.

   • On the Operations tab, find the custom webhook operation.

   • Open the operation's menu and select Manage Alert Rules.

   • Select the alert rules that should send notifications to Webex.

   • Select Save.

   

   Manage Alert Rules panel

Troubleshooting

Symptom	Check
The custom webhook test fails	Confirm that Target is https://webexapis.com, Path is /v1/messages, and the final URL does not redirect.
No message appears in Webex	Confirm that roomId belongs to the intended space and the bot is a member of that space.
Authentication fails	Confirm that Bearer Token contains the Webex bot access token, not an expired personal access token.
Webex rejects the request body	Confirm that the body is valid JSON, contains roomId, and uses markdown for the message.
Variables do not render	Confirm that the variables use the supported syntax in Webhook Variables.
A preset value is missing	Add the connector target, bearer token, operation path, and roomId. The preset provides only the sample body and Content-Type: application/json header.

For more information about custom webhook operations, final URL behavior, JSON body requirements, Handlebars syntax, and testing, see Custom Webhooks.