Webhook Integration : Send alerts to ServiceNow

overview this guide shows how to use webhook to export nile service block (nsb) alerts to servicenow — for log analysis and archiving alerts that export via webhook to servicenow are slas nile service availability, coverage, and capacity alerts infrastructure infrastructure dhcp, dns, radius, and internet availability alerts applications application availability and latency alerts security wireless intrusion detection (wids) alerts prerequisites servicenow cloud instance, with access from nile cloud administrator rights to the nile portal servicenow setup create servicenow development instance for testing login to servicenow\ you can create a new account if you don’t have one yet servicenow provides a developer instance (for free) that can be used for nsb integration tests this document uses a developer instance for this purpose the steps will be the same in creating a production servicenow instance to create a developer instance, go to https //developer servicenow\ com/dev do create a developer account, then log in to build a developer servicenow to create a developer instance, click on start building, then request an instance after building the developer instance, you will be provided an instance url , login user name , and password (in our example, the developer instance url is https //dev119912 service now\ com and the username/password is “admin/=ez g23ijdti”) important note if you do not access the developer instance for a few days, the instance state will be changed to hibernate after some additional time, the instance will be deleted login to the new instance using your admin account create a servicenow new field for nile service servicenow provides default fields for incidents, and these can be extended we will need to add a new field, “external id” as an example to the incident table this field will be used to correlate nile alerts to servicenow incidents from the all tab, click the down caret to expand system definition ; under system definition, select tables the list of tables (model) in the servicenow is shown below search for incident table by keying “incident” in the search field from the search results, click on the link “incident” in the “columns” tab, add the label “incident”, the name “incident”, then click new to update the table schema/model with the nile incident column from the column option, set type as “ string ”, make the column label as “ external id ” and the column name will auto generated “u external id” we will use the column name for the integration with nile webhooks in this example, the column name is “ u external id ” specify the max length as 32 and click “ submit ” create servicenow new field for nile service the next step is to create a java scripted rest apis which handles the webhooks requests from nile notification services below is the java script that we will use to create the api (function process( / restapirequest / request, / restapiresponse / response) { request body data; var alert = request body data; var state = 2; if (alert alertstatus == 'resolved') { state = 6; } var inc = new gliderecord('incident'); inc addquery('u external id', '=', alert id); inc query(); if (inc next()) { inc state = state; if (state == 6) { inc close code = 'closed/resolved by caller'; inc close notes = 'closed by api'; } inc update(); } else { inc initialize(); inc u external id = alert id; inc short description = alert alertsubject; inc description = alert alertsummary + " for " + alert duration; inc insert(); } response setstatus(200); })(request, response); note you can customize the script for more information on servicenow api scripts use the following url https //docs servicenow\ com/bundle/rome application development/page/integrate/custom web services/reference/r scriptedrestservicescriptexamples html https //docs servicenow\ com/bundle/washingtondc application development/page/build/custom application/concept/build applications html to add the script api to servicenow, navigate to all and filter on “ scripted rest apis ” and click the link script rest aps link will show the list of existing rest apis click on new to create a new api for nile webhooks in the name field, provide an api name in our example, we used “ nile alert ” click on submit search rest apis name “ nile alert ” and double click on the link to open the api url to add the api script, under the resources tab click new select http method as post in the script section, copy and paste the nile script under the security tab, make sure the requires authentication checkbox is enabled click on submit make a note of the resource path url; it’s needed for integration and api testing in our example api resource url is “ /api/832604/nile alert ” , this completes the servicenow setup testing servicenow api using postman we will need a fully qualified rest api path for servicenow, the fully qualified path is https // + \<instance name> + \<resource path> in our example, it will be https //dev119912 service now\ com/api/832604/nile alert you will need the url for api postman verification and nile integration open postman application select post ,and provide the api url click on authorization , select type basic auth, andprovide servicenow instance admin credentials (user/password admin/=ez g23ijdti) nile portal required a basic token for integration postman will generate a basic token from authentication, and you will need the key (token) to configure nile webhook servicenow integration to view and copy the basic token, click on headers, it will show you all headers including authorization , copy authorization header key values including “basic” keyword example the authorization token will be ” basic ywrtaw46puvakmcym0lqzfrp to test the api, we will need to generate a test incident, we can use a simple json alert payload that simulates “alert notifier” / “notification services”, below is a simple schema to generate a simple alert all the fields in the json are string type { "id" "9c4a3f89 327f 4100 8cc0 d1bcd90a71ac", "alertstatus" "created", "alertsubject" "new nile alert \[radius]", "alertsummary" "detected delay with radius server 10 1 2 10 responses", "starttime" "dec 28, 2020 7 07 00 am", "duration" "5 minutes", "site" "site 1", "building" "building 1", "floor" "floor 1" } to generate the test alert, select the body option, click on raw , change format to json , and copy and paste the incident json example as below click on send and verify the status, the status should be 200 ok , this means the rest api request was completed without any error verify the incident is created under servicenow, from the servicenow instance, under all, filter on service desk , then click on incidents, incident table will be opened, first incident will be the test incident that we generate using postman nile control center setup add servicenow webhooks to nile portal login to nile portal using an admin account, and navigate to settings select global settings select integration; click on “ + ” sign to add servicenow webhooks fill out servicenow webhooks info name webhooks name example “ service now ” url servicenow api url “ https //instance name + resource path ” in our example, it will be https //dev119912 service now\ com/api/832604/nile alert token basic authentication token generated by postman in our example “ basic ywrtaw46puvakmcym0lqzfrp ” click on save to save the config enable webhooks alert subscription nile portal has options to send specific alert to admin via email or to webhooks these alert groups are slas nile service availability, coverage, and capacity alerts infrastructure infrastructure dhcp, dns, radius, and internet availability alerts applications application availability and latency alerts security wireless intrusion detection (wids) alerts login to nile portal using an admin account and navigate to global settings select integrations >setup integrations selecting email will enable alerts to be sent to a logged in admin selecting webhooks will send alerts via webhook (in our example service now) note the selected options are saved automatically webhook enhancements the nile portal now includes the following webhook enhancements custom hostname for nile elements (ne) you can now configure a custom hostname for nile elements the configured hostname is reflected in webhook notifications, enabling better alignment with your internal naming conventions and downstream systems in addition, the download function on the nile device inventory page now includes the operator/admin modified hostname alongside other device parameters and also retains the original default device name for cross reference closet added to location hierarchy the closet level is now included in the location hierarchy and is visible in the location column on the inventory page this provides more granular physical context for device placement additional webhook payload attributes as separate fields the webhook notification json body now exposes several attributes as dedicated fields, simplifying parsing and integration newly available fields include custom ne name device type serial number ( sn ) severity deviceid (a nile generated unique identifier for continued reference and correlation) webhook “test connection” button in nile portal a test connection button is now available for webhook configurations in the nile portal this allows you to quickly validate endpoint reachability and confirm that your receiving system can successfully accept and process webhook payloads before using the webhook in production workflows verify nile events under servicenow and report login to nile portal as an admin click on alert icon (triangle on left side) click on alerts tab verify nile alerts browse to nile alert & audit under alerts list, verify nile created alerts login to servicenow instance as an admin verify nile alerts are created as incidents under servicenow from the servicenow instance, under all, filter on service desk, then click on incidents, the incident table will be opened click on the blue link of the incident number to see the detail