Creating Webhooks

RUCKUS AI allows you to configure Webhook URL addresses to receive real-time notifications when incidents are created or updated in the application – much like e-mail notifications. Webhooks help applications to communicate with each other in real-time and typically use a message or payload to communicate between each other. The message or payload contains real-time information about the incident.

Sample Webhook Message with Incident Details

For example, RUCKUS AI communicates with ticketing applications in ServiceNow and Salesforce (SFDC) via webhooks. Through webhooks, the incidents generated in RUCKUS AI appear in the ServiceNow and Salesforce applications, in real-time. Following is a work-flow to configure Webhooks for ServiceNow and SFDC applications.

On the Navigation bar, click Administration > Account Management > Webhooks. The Webhooks page is displayed.
Webhooks Page

The Webhooks page displays the count of Total Webhooks and all the created webhooks are displayed in the webhooks table.

The webhooks table has the following attributes:
  • Status: Displays green color if webhook URL is enabled or grey color if it is disabled.
  • Name: Displays the name of the webhook.
  • URL: Displays the webhook URL created by appending the domain URL and the base API path from the other application.
  • Resource Group: Displays the associated resource group.

Under each attribute is a search field to limit the webhooks list based on the search criteria.

Click Edit icon () to edit the webhooks information. Click Delete icon () to delete the webhooks.

You can select the number of webhooks displayed in the table from the Show rows drop down at the bottom of the table. The range is from five webhooks per table to 100 webhooks per table.

To create a webhook and integrate it with ServiceNow, refer to Integrating RUCKUS AI Incident Webhook with ServiceNow Application

To create a webhook and integrate it with your email, refer to Creating Email Notification for RUCKUS AI Incidents using Zapier Application.

To create a webhook and integrate it with Zapier, refer to Create a New Salesforce Case for RUCKUS AI Incident using Zapier Application.

To update a webhook that is integrated with Zapier, refer to Updating an Existing Salesforce Case for RUCKUS AI Incident using Zapier Application.

Integrating RUCKUS AI Incident Webhook with ServiceNow Application

  1. Login to the ServiceNow instance.
    Logging into ServiceNow
  2. Under System Web Services, select Scripted Rest APIs.
    Scripted Rest APIs Configuration
    A new record to configure the Scripted REST Service is displayed. Configure the following.
    • Name: Enter the name of the service.
    • API ID: Enter the API ID.
    • Protection Policy: Select the appropriate policy from the menu.
    • Application: Enter the scope of the application. In this example scope is set to Global.
    • API Namespace: A system generated value is populated.
  3. Click Submit.
    The service is created and listed.
  4. Click the service. Under Resources, click New to provide the endpoint for the service.
  5. Select the HTTP method as POST.
  6. In Script, enter this code for the endpoint to process the request:
    Note: Ensure that the spacing is retained when you copy and paste the code.
    (function process(/*RESTAPIRequest*/ request, /*RESTAPIResponse*/ response) {
      // Secret shared between Ruckus Analytics (RA) and ServiceNow
      // to ensure the authenticity of data received.
      var secret = "<secret>";
    
      // Change value to assign incident to specific group,
      // leave as is to not assign to any group
      var assignment_group = "<assignment_group>";
    
      // Change value to assign incident to specific person,
      // leave as is to not assign to any person
      var assigned_to = "<assigned_to>";
    
      // Mapping of RA incident severity to
      // ServiceNow incident Impact and Urgency field
      var impactAndUrgencyMap = {
        P1: { impact: 1 /* High */, urgency: 1 /* High */ },
        P2: { impact: 2 /* Medium */, urgency: 1 /* High */ },
        P3: { impact: 2 /* Medium */, urgency: 2 /* Medium */ },
        P4: { impact: 3 /* Low */, urgency: 3 /* Low */ }
      };
    
      // Mapping of RA incident status to
      // ServiceNow incident State field
      var stateMap = {
        'new': 1 /* New */,
        'ongoing': 1 /* New */,
        'finished': 6 /* Resolved */
      };
    
      var data = request.body.data;
      // 1. Ensure request uses correct shared secret key
      if (data.secret == secret) {
        var mode; // insert or update
        var event = data.payload;
    
        var inc = new GlideRecord('incident');
    
        // 2. Check if incident exists
        inc.addQuery('number', event.id);
        inc.query();
    
        if (inc.hasNext()) {
          inc.next();
          mode = "update";
        } else {
          inc.initialize();
          mode = "insert";
        }
    
        // 3. Add/update fields
        inc.number = event.id;
        inc.state = stateMap[event.status];
        inc.impact = impactAndUrgencyMap[event.severity].impact;
        inc.urgency = impactAndUrgencyMap[event.severity].urgency;
        inc.short_description = event.title;
        inc.description = getDescription(event);
    
        // 4. Assign incident to specific group or person
        if (assigned_to != "<assigned_to>") {
          inc.assigned_to = assigned_to;
        }
        if (assignment_group != "<assignment_group>") {
          inc.assignment_group.setDisplayValue(assignment_group);
        }
    
        // 5. Insert/Update the incident
        inc[mode]();
    
        var status = mode + (mode == 'insert' ? 'ed' : 'd');
        gs.info('incident ' + event.id + ' ' + status);
      } else {
        gs.warn("Invalid secret to run Ruckus Analytics webhook");
      }
    
      // Respond to the Webhook
      response.setStatus(200);
    
      /**
       * Generate description for incident
       */
      function getDescription (event) {
        return [
          'Incident URL: ' + event.link,
          '',
          'Details:',
          '------------------------------------------------',
          'Client Impact Count: ' +
            event.impactedClientCount +
            ' of ' +
            event.clientCount +
            ' (' + event.impactedClientPercentage + ')',
          'Incident Category: ' + event.category,
          'Incident Sub-Category: ' + event.subCategory,
          'Type: ' + event.impactedAreaType,
          'Scope: ' + event.impactedAreaName,
          'Hierarchy: ' + event.impactedAreaHierarchy,
          'Duration: ' + event.duration,
          'Event Start Time: ' + event.startTime,
          'Event End Time: ' + event.endTime,
          '',
          'ROOT CAUSE ANALYSIS:',
          '------------------------------------------------',
          event.rootCauses,
          '',
          'RECOMMENDED ACTION:',
          '------------------------------------------------',
          event.recommendations
        ].join('\n');
      }
    })(request, response);
  7. In var secret, set the secret value for data authentication.
  8. In var assignment_group, assign the RUCKUS AI incident to a specific group within ServiceNow.
  9. In the Security tab, uncheck Required Authentication.
  10. Click Submit.
  11. Log in to the RUCKUS AI account.
  12. On the Navigation bar, click Administration > Account Management > Webhooks. The Webhooks page is displayed.
  13. Click Create Webhooks.
    The Create Webhook dialog box is displayed.
    Create Webhook Dialog Box
  14. Complete the following fields:
    • Name: Enter the name of the webhook.
    • Webhook URL: Enter the URL by appending the domain URL (for example, https://dev-123.service-now.com) and the Base API Path from the ServiceNow record (for example, /api/93874/ruckus_analytics_incidents).
    • Secret: Enter the secret key generated for authentication from the service record.
    • Resource Group: Select the resource group that you want to associate with the webhook URL. Any incident created within that resource group will be notified via the webhook URL to the ServiceNow application.
    • Event Types: Select the event types from severity P1 to P4.
    • Enable: If webhook URL is enabled, ServiceNow will receive notifications about the incidents. If webhook URL is enabled, the status appears green and appears grey if it is disabled.
  15. Click Create. The new webhook is added to the Webhook page. This URL will establish communication between ServiceNow and RUCKUS AI and reflect incidents generated within resource groups, in real-time.
    You can edit the Webhook URL configuration by clicking the icon. Click Update to saved edits to the configuration.

Creating Email Notification for RUCKUS AI Incidents using Zapier Application

Before proceeding, ensure that you have a Zapier account and are logged into RUCKUS AI.
This section outlines the steps to create an automation using Zapier that triggers email notifications for RUCKUS AI incidents based on incoming data received via webhooks. Whenever a new incident is triggered in RUCKUS AI, a notification is sent to your email with the incident details.

Complete the following steps to set up the automation to trigger email notification for RUCKUS AI incidents using Zapier:

  1. Go to the Zapier website and sign up for an account, or log in if you already have a Zapier account and access the Zapier web interface by clicking https://zapier.com/app/zaps.
  2. Click Create and select New Zap to start creating a new automation.
  3. Click Trigger and search and select Webhooks by Zapier as the trigger application. The Catch Hook in Webhooks by Zapier window is displayed.
    Zapier Workflow - Trigger Application and Events
  4. Select Catch Hooks as the trigger event and click Continue to configure Catch Hook trigger settings.

    After setting up the Catch Hook trigger, Zapier will generate a unique webhook URL. Copy this URL as it is used to configure webhook in RUCKUS AI as described in step 7.

  5. Log in to the RUCKUS AI account.
  6. On the Navigation bar, click Administration > Account Management > Webhooks. The Webhooks page is displayed.
  7. Click Create Webhooks.
    The Create Webhook dialog box is displayed.
  8. Complete the following fields:
    • Name: Enter the name of the webhook.
    • Webhook URL: Enter the webhook URL from the Zapier interface.
    • Resource Group: Select the resource group that you want to associate with the webhook. Any incident created within that resource group will be sent to Zapier via the webhook.
    • Secret: Enter secret key for data authentication between RUCKUS AI and Zapier.
    • Event Types: Select the event types from severity P1 to P4.
    • Enabled: If webhook URL is enabled, Zapier will receive notifications about the incidents.
    • Click Send a Sample Incident to continue integration on the Zapier application. When the incident sample has reached Zapier, a success message is relayed on the Create Webhook dialog box in the RUCKUS AI web interface.
  9. Click Create to save the configuration.
    The new configuration is listed in the Webhooks page.
  10. Go back to the Catch Hook in Webhooks by Zapier window in the Zapier web interface and click Test Trigger .
    A request message or payload from RUCKUS AI is displayed in the Zapier web interface. It contains information about the incidents.
  11. Click Continue with the selected record to continue configuring your Zap by adding additional steps, such as choosing an action application and setting up the desired action.
  12. Click Action and search and select Filter by Zapier as the action application. The Only Continue if... window is displayed.
    Zapier Workflow - Action Application and Events
  13. Click the Filter setup & testing tab and specify the conditions that incoming data must meet to proceed further in the Zap workflow. Options such as "field," "condition," and "value" are displayed to define the filtering criteria.
    1. Specify the condition to proceed only if there is an exact match of the secret key configured for webhook in the RUCKUS AI web interface for data authentication.
    2. Click +And to specify another condition to consider "Incidents" types as filtering criteria.
  14. Click Continue
  15. Add Email by Zapier as the action application.
    Zapier Workflow - Action Application and Email Setting
  16. Select Send Outbound Email as the action event you want to perform with Email by Zapier and click Continue.
  17. Configure the settings for the selected action event by specifying the recipient's email address, subject line, body content, and any other required parameters.
  18. Click Test Step to verify that Zapier can successfully send the email according to the configured settings.
  19. Click Publish. The newly created zap is listed in the My Zap window.
  20. Turn on the the toggle button to activate zap and start automating the process of sending emails based on webhook triggers.

Create a New Salesforce Case for RUCKUS AI Incident using Zapier Application

Ensure that you have Zapier account. Also ensure you are logged into Salesforce and RUCKUS AI.
Whenever a new incident is triggered in RUCKUS AI, a new case is created in Salesforce and updated as and when the incident is updated. Follow these instructions to setup the Zapier application to create a case in Salesforce.
  1. Login to the Zapier web interface by clicking https://zapier.com/shared/0ec3d66a9a6889681fdb83248838d6ca161c90c6.
  2. Click Try this Zap.
    A page displaying the webhook URL is displayed. This URL is used to integrate Salesforce cases with RUCKUS AI incidents, in real-time.
  3. Log in to the RUCKUS AI account.
  4. On the Navigation bar, click Administration > Account Management > Webhooks. The Webhooks page is displayed.
  5. Click Create Webhooks.
    The Create Webhook dialog box is displayed.
  6. Complete the following fields:
    • Name: Enter the name of the webhook.
    • Webhook URL: Enter the webhook URL from the Zapier interface.
    • Resource Group: Select the resource group that you want to associate with the webhook URL. Any incident created within that resource group will be notified via the webhook URL to the Salesforce application.
    • Secret: enter secret key for data authentication between RUCKUS AI and Zapier.
    • Enable: If webhook URL is enabled, Salesforce will receive notifications about the incidents.
    • Click Send a Sample Incident to continue integration on the Zapier application. When the incident sample has reached Zapier, a success message is relayed on the Create Webhook dialog box in the RUCKUS AI web interface.
  7. Click Create to save the configuration.
    The new configuration is listed in the Webhooks page.
  8. In the Zapier web interface, In Catch Hook, click Test Trigger .
    A request message or payload from RUCKUS AI is displayed in the Zapier web interface. It contains information about the incident.
    Zapier Web Interface
  9. Click Continue.
  10. In Only Continue if... , go to Filter setup & testing and enter the same secret key that was included in the RUCKUS AI web interface for data authentication.
  11. Click Continue.
  12. In Utilities, go to Set up action and in the lookup table, map the RUCKUS AI incidents status with the Case status in Salesforce.
  13. Click Test & Continue.
  14. In Utilities, go to Set up action and in the lookup table, map the RUCKUS AI incidents severity with the priority of cases in Salesforce. For example, P1 incidents will be marked High priority, P2 and P3 as Medium and P3 as Low priority incidents.
  15. Click Test & Continue.
  16. In Find Record by Query in Salesforce, go to Choose account, and select your Salesforce account or login to your account and authorize Zapier to manage records in Salesforce on your behalf. This step ensures no new cases are recorded when existing cases are present.
  17. Click Continue.
  18. Under Setup Action, select Case as the Salesforce object.
    Note: Do not change the WHERE clause field.
  19. Click Skip Test.
  20. Click Close.
  21. Click Continue.
  22. Under Only continue if... , go to Filter setup and testing and click Continue.
  23. In Create Record in Salesforce, go to Choose account and select your Salesforce account.
  24. Under Setup Action, select Case as the Salesforce object. Set the other fields as necessary. Modify the fields as required, such as changing the description or assigning the Salesforce case to a particular person or group.
    Note: Do not change the "Subject" as it is used when updating a case.
  25. Click Continue.
    A Salesforce recorded is now created.
  26. Login to Salesforce Web interface. A new case is created as shown.
    New Record in Salesforce
  27. In the Zapier web interface, click Turn on Zap.
    Whenever an incident occurs in RUCKUS AI, the changes will reflect in the Salesforce case as well.
    You can also update existing cases in Salesforce by following the same steps mentioned in the next section.