> For the complete documentation index, see [llms.txt](https://docs.thousandeyes.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.thousandeyes.com/product-documentation/integration-guides/custom-webhook-examples/webex-for-alert-notifs.md). # 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](https://developer.webex.com/) 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](https://developer.webex.com/messaging/docs/getting-your-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](https://developer.webex.com/create/docs/bots#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](https://help.webex.com/article/DOC-17678) 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](https://help.webex.com/en-US/article/n35gqwcb/Webex-App-%7C-Add-people-to-a-space) for platform-specific instructions. 5. Copy the space's `roomId`. * Open the Webex [List Rooms](https://developer.webex.com/messaging/docs/api/v1/rooms/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. ```json { "items": [ { "id": "", "title": "ThousandEyes-Webhook-Test" } ] } ``` **Result:** You have the `roomId` required for the custom webhook body. ## Creating the Custom Webhook Connector 6. In the ThousandEyes platform, select **Manage > Integrations > Integrations 2.0**. 7. On the **Integration Templates** tab, select **Custom Webhook**. 8. 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. 9. Select **Save & Assign Operation**. **Result:** ThousandEyes saves the connector and opens the custom webhook operation settings. ## Creating the Custom Webhook Operation 10. 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](https://1112912342-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M4QARF6s57qxMrOHDTZ%2Fuploads%2Fgit-blob-162eaae875bbd3b5420b896c570ad5303b5e7d42%2Fcustom-webhook-webex-7.png?alt=media\&token=e8e11866-2519-43c2-a153-2e8d6f370f56) 11. 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](https://developer.webex.com/messaging/docs/api/v1/messages/create-a-message) API at `https://webexapis.com/v1/messages`. 12. Replace the preset body with the following JSON, then replace `` 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. ```json { "roomId" : "", "markdown" : "ThousandEyes Alert{{#eq type.id 2}} Triggered{{else}} Cleared{{/eq}}{{#if alert.test}} for {{alert.test.name}}{{/if}}\nAlert ID: {{alert.id}}{{#if alert.test}}\nTest Name: {{alert.test.name}}\nTarget/s: {{#each alert.targets}}{{description}}{{#unless @last}} {{/unless}}{{/each}}{{/if}}\nAlert Rule: {{alert.rule.name}} - {{formatExpression alert.rule.expression}}{{#if alert.details}}\nDetails: {{alert.details.size}}{{/if}}\nSeverity: {{alert.severity.display}}\nAlerts Link: https://app.thousandeyes.com/alerts/list?__a={{alert.rule.account.id}}&alertId={{alert.id}}" } ``` 13. 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](https://docs.thousandeyes.com/product-documentation/integration-guides/custom-webhooks/webhook-vars). ## Testing the Integration 14. In the custom webhook operation, select **Test**. ![Custom webhook test success message](https://1112912342-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M4QARF6s57qxMrOHDTZ%2Fuploads%2Fgit-blob-7d34fe2187ff195c24ed0b69256ed00952cc1b32%2Fcustom-webhook-webex-8a.png?alt=media\&token=a2a8a778-7742-4b99-b9f4-299690dbdc34) 15. 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](https://developer.webex.com/messaging/docs/api/v1/messages/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` | 16. Select **Save Integration**. **Result:** ThousandEyes saves the connector and custom webhook operation. 17. 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](https://1112912342-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M4QARF6s57qxMrOHDTZ%2Fuploads%2Fgit-blob-5c08e530e8ddf3b32735ff19d41b15643cd350a5%2Fthousandeyes-manage-alert-rules.png?alt=media\&token=1bb0d629-cf80-42d6-b1b8-27a7808bca31) ## 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](https://docs.thousandeyes.com/product-documentation/integration-guides/custom-webhooks/webhook-vars). | | 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](https://docs.thousandeyes.com/product-documentation/integration-guides/custom-webhooks).