Integrating Runscope API Monitoring with ServiceNow

Note: if you don't see Advanced Webhooks under your team's Connected Services page, please contact support so they can enable it for you.

ServiceNow is a flexible online platform that helps customers transform their digital workflows. One of the ways it can be used is to help IT departments with incident management.

In this tutorial, we're going to show you how to create a webhook receiver (as a Scripted REST API) inside of ServiceNow, and how to set up Advanced Webhooks in your Runscope account to send test result notifications to ServiceNow to automatically create incidents in case of an API failure.


Requirements


Creating a Scripted REST API in ServiceNow

First, log in to your ServiceNow account. On the left-hand side search box, type "Scripted REST". Click on Scripted REST APIs under System Web Services -> Scripted Web Services:

The SerivceNow logged in dashboard, highlighting the Scripted REST APIs option on the left-hand side menu

Click on New to create a new API service:

The SerivceNow Scripted REST APIs page, highlighting the New button at the top

Give your API a name, and an API ID (we'll use "Runscope Webhooks" for our example). You can leave Protection Policy as "-- None --". Click on Submit:

The ServiceNow Scripted REST Service page, showing the details for creating a new API with the fields Name and API ID filled out

You'll be taken back to the list of Scripted Web Services. Search for the API we just created and click on it:

The ServiceNow Scripted REST APIs list view, highlighting the new API we created in the preivous step with the name Runscope Webhooks

Scroll down to the Resources tab and click on New:

The ServiceNow Scripted REST API details view for our newly created API, highlighting the Resources tab at the bottom of the page and the New button

Give your resource a name (we'll use "event") and change the HTTP method to POST:

The ServiceNow REST API resource editor page, highlighting the Name field filled out, and the HTTP Method dropdown set to POST

Scroll down to the Script section and add the following snippet:

(function process(/*RESTAPIRequest*/ request, /*RESTAPIResponse*/ response) {
  var apiKey = request.queryParams['apiKey'];
  var secret = "<secret>";
  if (apiKey == secret) {
    var event = request.body.data;

    var inc = new GlideRecord('incident');
    inc.initialize();

    var short_description = "Runscope Webhook - ";
    short_description += event.test_name;
    inc.short_description = short_description;
    inc.description = event.bucket_name + " - " + event.test_name;
    inc.work_notes = "Test run URL: " + event.test_run_url;

    inc.number = event.test_run_id;
    inc.state = 1;
    inc.impact = 2;
    inc.urgency = 2;
    inc.priority = 2;

    // optional - specific person to assign the incident to
    // inc.assigned_to = "<email>";

    inc.assignment_group.setDisplayValue("<group>");

    var comments = "Runscope Test URL: " + event.test_url;
    comments += "\nRunscope Test Run URL: " + event.test_run_url;

    inc.comments = comments;
    inc.insert();
  } else {
    gs.warn("Invalid API Key for Runscope Webhook");
  }

  // Runscope expects a 200 status code response back
  response.setStatus(200);
})(request, response);

Important: there are three variables in the script that you need to update:

  • <secret> - required - a random string, such as a UID. Save this value as we'll use it later when setting up the Runscope webhook.
  • <group> - required - the group that you want to assign the incident to.
  • <email> - optional - the specific person to assign the incident to.

Note: if you want to customize the code and add more information to the incident, check out the Runscope webhook payload to see what properties are available.

In the Security tab, uncheck the Requires authentication checkbox (we will use the "secret" GUID variable to protect access to the API). Click on Submit:

The ServiceNow REST API editor page, highlighting the Security tab at the bottom of the page with the Requires Authentication checkbox unchecked

Back on our Scripted API page, look for the Base API Path field for our newly created API:

The ServiceNow REST API details page for our newly created API, highlighting the Base API Path field that needs to be copied for the next steps

Our API endpoint will be something like this:

https://<yourInstanceName>.service-now.com/<baseApiPath>?apiKey=<secret>

Sending Runscope Notifications to ServiceNow via Advanced Webhooks

Log in to your Runscope account, click on your profile on the top-right and select Connected Services. Search for "Advanced Webhooks", and click on Connect:

The Advanced Webhooks box found in the Connected Services page for a logged in Runscope user

Give your new integration a name (we'll call ours "ServiceNow Integration"), and select a Threshold. We recommend leaving Notify when a test run is completed as the threshold for now for testing purposes:

The Runscope logged in page for setting up a new Advanced Webhooks integration, highlighting the Description field with the name of our new integration, and the Threshold option set to Notifiy when a test run is completed

In the URL field, paste your API endpoint that you got from the previous section. It should look similar to this:

https://<yourInstanceName>.service-now.com/<baseApiPath>?apiKey=<secret>
The Runscope logged in page for setting up a new Advanced Webhooks integration, highlighting the URL field with the URL for our ServiceNow REST API created in the previous steps

Important: make sure to replace <secret> at the end with the secret UID you used in the script.

Click on Save Changes.

Testing Our Integration

Now to test our integration, we need to enable it in one of our tests so Runscope can start sending webhooks to ServiceNow. Go to one of your buckets dashboard and create a new test.

In the test editor, open the environment settings, click on the "Integrations" tab and toggle the ServiceNow integration we just created to On:

The Runscope test editor, highlighting the Integrations tab in the environment editor, with the Advanced Webhook integration we created in the previous steps toggled on

Click on Save & Run to run the test.

Now let's go back to ServiceNow. On the left-hand side search box, type "Incidents". Under the Service Desk section, click on Incidents:

The ServiceNow logged in dashboard, showing the Incidents option highlighted on the left-hand side menu

And you should see a new incident created on the top of the list with information from your Runscope test run:

The ServiceNow incidents list page, highlighting an incident showing the details for a Runscope Webhook payload

And we have our integration working!

Now that we know the ServiceNow API and the Runscope integration are working, remember to adjust the Advanced Webhooks thresholds so alerts are only sent when you want them to. You can do that by going to the Connected Services page, clicking on the edit icon next to your integration:

The Runscope Connected Services page, highlighting the Edit icon next to an integration already set up in a Runscope account

And then changing the threshold options, so you can configure how often you want to create incidents for API failures:

The Runscope Advanced Webhooks details page, highlighting the Threshold option set to Notify only when a test run fails, to only create incidents when API monitors fail after the user has tested their integration and made sure it is working


Having trouble configuring ServiceNow? Contact our support team.

Need help? We have you covered.

View the docs or contact our support team and we'll get back to you as soon as we're able to respond.