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
• Sending Runscope Notifications to ServiceNow via Advanced Webhooks
• Testing Our Integration

Requirements

• Runscope account
  • Advanced Webhooks integration enabled (go to your Runscope team Connected Services page, and search for "Advanced Webhooks". If you don't find it, please reach out to support)
• ServiceNow account (you can create a free developer account here)

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:

Click on New to create a new API service:

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:

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

Scroll down to the Resources tab and click on New:

Give your resource a name (we'll use "event") and change the HTTP method 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:

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

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:

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:

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>

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:

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:

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

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:

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

Having trouble configuring ServiceNow? Contact our support team.