Skip to content

ServiceNow


The ServiceNow notification target sends Guance alerts as POST JSON to a ServiceNow receiving endpoint. After parsing the alert, the receiving flow can create an Incident (ticket) according to business rules in the instance or trigger other processing flows.

This article uses Scripted REST API: a custom HTTP endpoint created by a ServiceNow administrator. The receiving script converts alert fields into ticket fields and controls ticket creation, deduplication, routing, and status maintenance.

Configure the receiving endpoint in ServiceNow

Creating an API and resource requires the ServiceNow web_service_admin or admin role. The calling account must also meet the authentication policy, ACL (access control rules), and permission requirements of the target ticket table for the receiving resource.

  1. Go to All > System Web Services > Scripted REST APIs, create an API, and enter a name and API ID.
  2. In the Resources related list, click New, create a resource, select POST, and set the resource path, for example /notification.
  3. Keep or configure the application/json request format. In Script, read the alert JSON through request.body.data and complete the ticket field mapping. See the example receiving script below.
  4. In the resource's Security, enable Requires authentication. To restrict endpoint access, enable Requires ACL authorization and select an ACL of type REST_Endpoint; if the ACL field is left blank, the parent API's ACL is used. Configure endpoint access permissions and permissions for the target ticket table and fields separately.
  5. Prepare authentication credentials according to the instance policy. For initial validation, you can use Basic authentication if the instance allows it; prepare an integration account and password with permission to call the endpoint and create tickets. You can also use Bearer Token or API Key.
  6. Save the resource and obtain the complete HTTPS URL containing the instance domain, namespace, API ID, and resource path.

The URL structure is as follows. version is required only when the API uses versioning; use the address actually generated for the resource:

https://<instance>.service-now.com/api/<namespace>/<version>/<api_id>/<resource_path>

For details, see Scripted REST API, Create a POST resource, Resource ACL configuration, and API access policies. Menus and authentication capabilities depend on the customer's instance version.

Example receiving script

The following example creates one Incident for each notification: title is written to the short description, and message plus the full notification JSON are written to the description, preserving the workspace, event context, and backlink. Multiple events in a single aggregated notification are stored in the same ticket.

Validate the script in a test instance and adjust it according to the instance's mandatory fields, field lengths, application access permissions, and business rules before use. If an aggregated notification is long, either split it into multiple tickets or save the full content as an attachment, depending on the instance's field capacity. Every test request creates a ticket.

(function process(request, response) {
    var data = request.body.data;
    if (!data || typeof data !== 'object' || Array.isArray(data)) {
        response.setStatus(400);
        response.setBody({ error: 'JSON object required' });
        return;
    }

    var incident = new GlideRecordSecure('incident');
    incident.initialize();
    if (!incident.canCreate() || !incident.short_description.canWrite() ||
        !incident.description.canWrite()) {
        response.setStatus(403);
        response.setBody({ error: 'Incident creation is not permitted' });
        return;
    }

    incident.setValue('short_description', String(data.title || 'Monitoring notification'));
    incident.setValue('description', String(data.message || '') +
        '\n\n' + JSON.stringify(data, null, 2));
    var sysId = incident.insert();
    if (!sysId) {
        response.setStatus(500);
        response.setBody({ error: 'Incident creation failed' });
        return;
    }

    response.setStatus(201);
    response.setBody({ sys_id: String(sysId), number: incident.getValue('number') });
})(request, response);

This example uses GlideRecordSecure to create tickets according to the ACL of the current calling user. Depending on business needs, the receiving script can also iterate over events to create separate tickets for each event, or update existing records by event identifier.

For the scripting API, see ServiceNow Scripted REST examples, Record creation permission canCreate(), Field write permission canWrite(), and RESTAPIResponse.

Create a notification target in Guance

Go to Monitoring > Notification Targets > Create Notification Target, and select ServiceNow.

  1. Enter a name to identify the notification target in the list and in alert policies. The name must be unique within the current workspace and can contain up to 200 characters.
  2. In Webhook URL, enter the complete HTTPS URL of the POST resource above, using the final receiving address.
  3. For Authentication Method, select Basic and enter the username and password allowed by the endpoint; or select another authentication method according to the receiving endpoint configuration.
  4. Enable Custom Request Headers as needed, and enter any additional keys and values required by the receiving endpoint.
  5. Click Send Test Notification, preview and confirm the send, and verify the received request, script execution, and generated ticket in ServiceNow.
  6. Configure operation permissions and save the configuration.
  7. In the Alert Policy, select this notification target and configure the event severity levels and scope to send.

Authentication methods and request headers

The API access policy for the receiving resource must allow the authentication method you select. The platform sends requests with the credentials you provide; you are responsible for obtaining and renewing tokens.

Authentication method Value to enter Receiving endpoint preparation
Basic Username, password Use an integration account allowed by the instance; the username must be non-empty and must not contain a colon.
Bearer Token Token Obtain a valid access token according to the instance's OAuth configuration and enter the raw value; the system adds the Bearer prefix. Renew it promptly after expiration or revocation.
API Key Request header name, API Key Complete the API Key configuration below. Enter the request header name according to the instance configuration, for example x-sn-apikey; if the instance requires a prefix, enter the complete key value including the prefix.
No authentication — Set custom request headers according to the actual authentication requirements of the receiving resource.

After the instance begins enforcing Basic Auth Restriction, the integration account must also meet the allowed conditions, for example, it must be set as a Web Services Access Only account or have the snc_basic_auth_api_access role, configured by an administrator according to the instance policy.

When using API Key, the person configuring it must have the api_service_admin and adaptive_auth_policy_admin roles. The instance must have the API Key and HMAC Authentication plugin (com.glide.tokenbased_auth) enabled, and the following configuration must be completed:

  1. Create an inbound authentication Profile for the API Key, and select the request header method for the authentication parameter, for example x-sn-apikey: Auth Header.
  2. Create a REST API Key, associate the calling user, and copy the generated token.
  3. Create and enable an API access policy, and associate the authentication Profile with the POST resource and applicable version of the target API.

For detailed steps, see ServiceNow API Key configuration; for obtaining an access token, see REST OAuth example. For instance restrictions on Basic, see Basic authentication restriction.

Custom request header names are deduplicated case-insensitively; headers generated by the selected authentication method take precedence over custom headers with the same name. Content-Type is fixed to application/json, and Accept defaults to application/json; the API Key request header name must be a valid name other than Content-Type.

Edit credentials

When editing with the same address, authentication method, and identity, leave the password, token, or API Key blank to retain the original value, or enter a new value to replace it. After changing the address, authentication method, username, or API Key request header name, you must enter the corresponding credentials.

Custom request header values are stored encrypted. When the above configuration remains unchanged, leave a saved header with the same name blank to retain its value, or enter a new value to replace it; deleting the row removes the header. After adding or renaming a header, or changing the above configuration, enter the complete header value.

Tests use the effective configuration in the current form; after saving, subsequent alerts use the new configuration.

Notification content and alert aggregation

The ServiceNow notification target follows the alert aggregation format of Simple HTTP Request and supports standard notifications, rule aggregation notifications, and smart aggregation notifications:

Field Description
title, message, status The title, body, and status of the current notification.
events List of events. A standard alert contains one event; an aggregated alert contains the corresponding group of events, preserving event context and backlinks.
workspace_uuid, workspace_name The ID and name of the workspace to which the events belong.
monitor_checker_links Monitor names and event list links in rule aggregation and smart aggregation notifications.

The alert policy determines which events make up a single notification; sending starts after the notification content is constructed. Notifications configured with an explicit delay are still sent at the specified time. The receiving script performs field conversion according to the alert structure above and then invokes the ticket processing logic in the instance.

Testing and troubleshooting

The fields in a test notification are based on the JSON actually received by the receiving endpoint. After testing the endpoint and authentication, use actual standard and aggregated alerts to verify field mapping and how events are processed.

An HTTP 2xx response from the receiving endpoint only indicates that the request completed. Also check the ServiceNow receiving logs, script execution, and ticket fields to confirm that the receiving flow performed the expected actions.

Symptom What to check
Authentication failure or no access permission Check the validity of the account, token, or API Key, as well as the access policy and ACL for the corresponding POST resource.
Request completes but no ticket is created Check the receiving script, target table permissions, mandatory fields in the instance, and business rules.
Ticket content is missing Check the field mapping for request.body.data and verify with actual standard and aggregated alerts separately; aggregated alerts require handling the events list.
Send failure Check the final HTTPS address, certificate, and network connectivity. HTTP 3xx redirects are treated as send failures.

Feedback

Is this page helpful?