ZDX supports the integration of IT Service Management (ITSM) via Incident Management (IM) and IT Operations Management (ITOM) via Event Management (EM). You can configure webhooks to deliver alerts about an application, device, or network performance. You can also use webhooks in an alert rule and configure multiple alert rules for the webhook. To learn more, see Configuring an Alert Rule.

Prerequisites

Ensure the following steps are completed prior to integrating with ServiceNow Event Management:

• Enable ITOM. To learn more, refer to ServiceNow IT Operations Management.
• Request the EM plugin and install it from the store when it is available. To learn more, refer to ServiceNow's Zscaler Digital Experience: Event Management.

To configure a webhook for ServiceNow, you must:

• 1. Create Service users and an OAuth 2.0 API endpoint in ServiceNow.

  Prior to creating a webhook, you must create users in ServiceNow and admins in the ZDX Admin Portal. Creating an OAuth 2.0 API endpoint is optional based on your authentication requirements.

  In your ServiceNow Console:

  • Create the required service user.

    1. Go to All > User Administration > Users.
    2. Click New.

    3. Enter your User ID. You can enter an email address as your User ID.

       Zscaler recommends using an email address in lieu of a user ID.

    4. Select the Web Services Access only checkbox.
    5. Click Submit.
    6. Reopen the user's record and click Set Password.
    7. In the Set Password window:
       1. Click Generate.

       2. Copy the generated password. Save the user ID and password information.

          See image.

          

          Close

       3. Click Save Password.
    8. Click Set Password on the User Record to save the password.

    9. In the Roles related list, click Edit.

       See image.

       

       Close

    10. Based on your service user's access needs, assign the respective role to the service user:
        • Incident Management

          If your service user requires access to IM:

          • For web service users that require access to IM, add the x_zsca2_zdx_manage.zdx_management role.
          • For users working with the Deep Tracing feature, add the x_zsca2_zdx_manage.zdx_dt_management role.

          Close
        • Event Management

          If your service user requires access to EM:

          • For web service users that require access to EM, add the evt_mgmt_integration role.
          • For active users that require managing the application, add the x_zsca2_zdx_manage.zdx_em_admin and evt_mgmt_user roles.

          Close
    11. Click Save.
    12. Click Update on the user's record.

    Close
  • (Optional) Create an OAuth 2.0 API endpoint.

    1. Search for oauth and go to Application Registry > New > Create an OAuthAPI endpoint for external clients.

       See image.

       

       Close

    2. In the Application Registries page:

       • Name: Enter a name for the OAuth support.
       • Client ID: This is not configurable. Save the Client ID for later use.
       • Client Secret: If this field is left empty, it auto-generates a Client Secret code. Save this Client Secret for later use.

       • Redirect URL: Enter your URL based on the cloud name of the ZDX tenant.

         The format must be:

         https://admin.<cloud name>/zdx/admin/webhooks

         Replace <cloud name> with your designated cloud name. To learn more, see What Is my Cloud Name for ZDX?

       • Refresh Token Lifespan: Enter your refresh token lifespan. Zscaler recommends a lifespan of 5 years from the current date.
       • Access Token Lifespan: Enter your access token lifespan. Zscaler recommends a lifespan of 1 hour to maximize reuse.

       See image.

       

       Close

    3. Click Submit to save your settings.

    Close

  Close
• 2. Create a ZDX Role in the ZDX Admin Portal.

  1. Add a ZDX Role to have the following permissions:
     • Diagnostics: Full
     • Webhooks: Full
     • User & Device Names: Visible
     • Configuration Access: Full
     • Alerts: Full
     • UCaaS Monitoring: View Only
  2. Assign the ServiceNow Role from the previous step to an existing ZDX Admin or by adding a ZDX Admin.
  3. Click Save.
  4. Activate the changes.

  Close
• 3. Configure a webhook in the ZDX Admin Portal.
  1. Go to Administration > Integrations > Webhooks > Add New Webhook.
  2. In the Add New Webhook window:
     • Name: Enter a name for the webhook.
     • Status: Select Enabled to enable the webhook.
     • URL: Enter one of the following URLs based on the integration:
       • Incident Management

         https://<your-instance-ID>.service-now.com/api/x_zsca2_zdx_manage/incident_management_api

         To learn more about installation and configuration details for ServiceNow Incident Management for ZDX, refer to the ServiceNow Store.

         Close
       • Event Management

         https://<your-instance-ID>.service-now.com/api/global/em/jsonv2                                                                

         To learn more about installation and configuration details for ServiceNow Event Management for ZDX, refer to the ServiceNow Store.

         Close
     • Authentication Type: Select your authentication type.
       • Basic

         For Basic Authentication:

         • Username: Enter the username of the previously created service user.
         • Password: Enter the password of the previously created service user.

         Click Save to save your webhook configuration.

         Close
       • OAuth

         For OAuth Authentication:

         • Application: Select ServiceNow.
         • Client ID: Enter the Client ID of the previously created OAuth 2.0 API endpoint.
         • Client Secret: Enter the Client Secret of the previously created OAuth 2.0 API endpoint.
         • Refresh Token Expiration: Select the date of when the refresh token expires from the previously created OAuth API 2.0 endpoint.
         • Click Authenticate Tenant.

         Click Save to save your webhook configuration.

         Close

  3. Click Test Webhook to see if it functions correctly.

     Test Webhook for OAuth does not post a test message on ServiceNow. Instead, it acquires the OAuth token.

  4. If the test is successful, a message indicating success appears.
     1. Click Save.
     2. Activate the changes.
  5. If the test is unsuccessful, an error message appears.
     • To troubleshoot the error, check for issues in the URL or the Authentication Type fields.
     • If the error persists, record to provide details of your error (e.g., screenshots or small video). Click Cancel so that the webhook configuration containing errors is not saved, and contact Zscaler Support with the error information.

  Close
• 4. Confirm the webhook test result and Deep Tracing connection on ServiceNow.

  To confirm if the webhook test result is on ServiceNow:

  1. Go to the ServiceNow service portal.
  2. In the Filter Navigator search bar, enter Zscaler Digital Experience.

  3. From the menu, select ServiceNow Incidents or ServiceNow Events module to see if the test webhook is recorded.

     See image.

     ServiceNow Incidents

     

     ServiceNow Events

     

     Close

  To confirm the Deep Tracing connection is on ServiceNow for IM:

  1. Go to the ServiceNow portal.
  2. In the Filter Navigator search bar, enter Zscaler Digital Experience.
  3. From the menu, select the ServiceNow Incidents module.
  4. Open your targeted incident record.
  5. Go to the Deep Tracing section and see if one of the following occurs to confirm the Deep Tracing connection:
     • The information message, "There are no related Deep Tracing Sessions." indicates there are no existing Deep Tracing sessions in ZDX related to the current incident.
     • A table of Deep Tracing sessions.

  Close

Deep Tracing is a type of Diagnostics session. In ServiceNow, you can only configure for Deep Tracing.

After the webhook configuration is complete and the ServiceNow users are assigned the Incident Management role, x_zsca2_zdx_manage.zdx_management, you can configure the Settings and Mapping modules in the ZDX application on ServiceNow to meet your alerting requirements. To learn more, see Understanding the ZDX Application Fields on ServiceNow.