Creating Webhooks

RUCKUS Analytics 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 Analytics communicates with ticketing applications in ServiceNow and Salesforce (SFDC) via webhooks. Through webhooks, the incidents generated in RUCKUS Analytics appear in the ServiceNow and Salesforce applications, in real-time. Following is a work-flow to configure Webhooks for ServiceNow and SFDC applications.

Integrating RUCKUS Analytics 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 Analytics incident to a specific group within ServiceNow
  9. In the Security tab, uncheck Required Authentication
  10. Click Submit.
  11. From the RUCKUS Analytics web interface, go to Admin > Webhooks.
    The Webhooks page is displayed showing information about the status of the webhook, name, URL and associated resource group.
  12. Click Create Webhooks.
    The Create Webhook page is displayed. Configure the following.
    • 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)
    • 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
    • Secret: enter the secret key generated for authentication from the service record
    • 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.
    • Event Types: select the event types from severity P1 to P4.
  13. Click Create. The new webhook is added to the Webhook page. This URL will establish communication between ServiceNow and RUCKUS Analytics 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.

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

Ensure that you have Zapier account. Also ensure you are logged into Salesforce and RUCKUS Analytics.
Whenever a new incident is triggered in RUCKUS Analytics, a new case is created in Salesforce and updated as an 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 Analytics incidents, in real-time.
  3. From the RUCKUS Analytics web interface, go to Admin > Webhooks.
    The Webhooks page is displayed showing information about the status of the webhook, name, URL and associated resource group.
  4. Click Create Webhooks.
    The Create Webhook page is displayed. Configure the following.
    • 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 Analytics and Zapier
    • Enable: If webhook URL is enabled, Salesforce will receive notifications about the incidents. If webhook URL is enabled, the status appears green and appears grey if it is disabled.
    • 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 Analytics web interface.
  5. Click Create to save the configuration.
    The new configuration is listed in the Webhooks page.
  6. In the Zapier web interface, In Catch Hook, click Test Trigger .
    A request message or payload from RUCKUS Analytics is displayed in the Zapier web interface. It contains information about the incident.
    Zapier Web Interface
  7. Click Continue.
  8. In Only Continue if... , go to Filter setup & testing and enter the same secret key that was included in the RUCKUS Analytics web interface for data authentication.
  9. Click Continue.
  10. In Utilities, go to Set up action and in the lookup table, map the RUCKUS Analytics incidents status with the Case status in Salesforce.
  11. Click Test & Continue.
  12. In Utilities, go to Set up action and in the lookup table, map the RUCKUS Analytics 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.
  13. Click Test & Continue.
  14. 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.
  15. Click Continue.
  16. Under Setup Action, select Case as the Salesforce object.
    Note: Do not change the WHERE clause field.
  17. Click Skip Test.
  18. Click Close.
  19. Click Continue
  20. Under Only continue if... , go to Filter setup and testing and click Continue
  21. In Create Record in Salesforce, go to Choose account and select your Salesforce account.
  22. 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.
  23. Click Continue.
    A Salesforce recorded is now created.
  24. Login to Salesforce Web interface. A new case is created as shown.
    New Record in Salesforce
  25. In the Zapier web interface, click Turn on Zap.
    Whenever an incident occurs in RUCKUS Analytics, 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.