Please note that this is a Technical Preview and consequently that all documentation, content, or updates may contain errors and are provided for limited evaluation only. The Technical Preview, the documentation, and any updates are provided on an ‘as-in’ and ‘as-available’ basis without warranty of any kind, whether express, implied, by operation of law or otherwise. Nexthink specifically disclaims all implied warranties of merchantability, fitness for a particular purpose and non-infringement.

Overview

The main advantage of configuring a Webhook is that Nexthink data from alerts or events can be pushed into a number of third-party tools in a variety of ways, depending on the destination.

In order to achieve such communication, Nexthink uses the Representational State Transfer (REST) API, a simple and widely accepted framework.

On the Webhook configuration page, there are three fields that are critical to performing an action on the destination third-party tool:

  • Method

  • Resource

  • Payload

In the following section, we will explain how to configure the aforementioned attributes to execute an action on the third-party tool.

Method

The REST standard is used over HTTP and it comprises a major portion of the uniform interface constraint, providing methods that you can use with Webhooks.

Below is the list of supported methods in Webhooks:

HTTP Method

CRUD

Description

POST

Create

POST is most-often utilized to create new resources.

PUT

Update/Replace

PUT is most often used for its update capabilities. You can PUT to a known resource URI with the request body containing the newly updated representation of the original resource.

PATCH

Update/Modify

PATCH is used for its modify capabilities. The PATCH request only needs to contain the changes to the resource and not the complete resource.

You can select the methods discussed above through a drop-down menu on the webhook configuration page:

Drop-down menu for the Request method

It can not be assumed that each method can be used in the same way for all vendors and providers of third-party tools. It is highly recommended to review the pertinent software documentation for each tool that a webhook was created for, in order to clearly understand the semantics of each method.

Resource

From the architectural perspective, resources are data sets that an API allows you to work with and which are accessible via endpoints. They have relationships with other resources as well as a set of allowed operations that can be carried out on them.

Resources are presented as sets of endpoints grouped on the basis of related data or the object they are allowed to work with. They have simple names that are easy to comprehend, making it easy for users to find the right endpoints. However, this may lead to overlooking essential functionality.

The value to be specified in the Resource is the action that is specified by the third-party REST API. The URI shouldn’t be added, since this value is concatenated to the Instance URL defined in Webhook Credentials. It can contain parameters (key=value) that the third-party tool requires.

Resource field

Examples of valid Resource values

Vendor API URL

Resource in Webhook

https://webhook.atlassian.net/rest/servicedeskapi/request

rest/servicedeskapi/request

https://api.4me.com/v1/requests

v1/requests

https://fra1.qualtrics.com/API/v3/users

API/v3/users

https://ven01063.service-now.com/api/now/v1/table/incident

api/now/v1/table/incident

Payload

Payload is the actual data pack that is sent with the POST/PUT/PATCH method in HTTP. It is the crucial information that you submit to the server when making an API request. The payload can be sent or received in various formats.

The only format that is accepted for this field is JSON.

Payload is dependent on the third-party tool that is used in the webhook. We recommend reviewing the vendor’s documentation to clearly understand the fields and values allowed by the third-party tool.

Nexthink data model variables used with payload

One of the biggest advantages of being able to push data from Nexthink into third-party tools is the ability to pass information about the event that has taken place within the payload.

Nexthink variables can be referenced using {{variable_name}} within any field that is reported in the payload.

Example of using Nexthink data-model variables in the payload:

{
    "description":"Ticket created for Zoom",
    "impact":"5",
    "short_description":"Alert for testing {{alert_config.id}} with priority purposes {{alert_config.name}}, {{alert_config.priority}}",
    "sys_created_by":"Nexthink Integration test",
    "urgency":{{alert_config.priority}}
}
CODE

List of available Nexthink datamodel variables

Nexthink datamodel variable

Type

Description

alert_config.name

string

Indicates the name of the alert config as given by the user

alert_config.type

enum

Type of the alert definition. “Metric threshold”

alert_config.threshold

float

The threshold defined in the query

alert_config.operator

enum

Comparison operator

alert_config.priority

enum

Priority of the alert as defined by the user in the alert config

diagnostic.alert.uid

string

Alert event uuid

diagnostic.alert.time

datetime

Time of the event

diagnostic.alert.context

string

Objects for which the alert has been triggered. If the alert is based on the NQL alert, these are the column names and values returned in query results. 

diagnostic.alert.context_hash

string

MD5 hash of the context json

diagnostic.alert.is_auto_recovery

boolean

If the alert was automatically recovered

diagnostic.alert.is_grouped

boolean

If the alert event is a grouping alert

diagnostic.alert.recovery_time

datetime

The time when an alert has been recovered

diagnostic.alert.trigger_time

datetime

The time when an alert has been triggered

diagnostic.alert.trigger_value

integer

Error value

diagnostic.alert.recovery_value

integer

Last value for aggregation

diagnostic.alert.status

enum

Open for an alert triggered

Closed for an alert that is recovered

diagnostic.alert.number_of_alerts

long

Count of alerts when data was aggregated, always 1 for 1 minute resolution

diagnostic.alert.timestamp

datetime

Error timestamp of the event with minute precision

Example from multiple providers and vendors

ITSM Tools

Creating an incident for ServiceNow:

Method: POST

Resource: api/now/v1/table/incident

Payload:

{
    "assignment_group":"Application Team",
    "business_service":"MS Teams",
    "caller_id":"Nexthink Alert",
    "description":"Alert created from the Alerts team,",
    "impact":"5",
    "short_description":"Alert for testing purposes David G {{alert_config.name}}",
    "sys_created_by":"Nexthink Integration test David G.",
    "urgency":4
}
CODE

Creating a problem for ServiceNow:

Method: POST

Resource: api/now/v1/table/problem

Payload:

{
   "impact":"1",
   "urgency":"2",
   "category":"Hardware",
   "short_description":"The alert: {{alert_config.name}} has been raised by Nexthink",
   "description":"The Alert {{alert_config.name}} has been raised automatically by Nexthink at {{diagnostic.alerts.time}}. The NQL query that triggered the alert is https://tinyurl.com/29k9xy8d",
   "assignment_group":"Application Team",
   "business_service":"MS Teams",
}
CODE

Creating an incident for BMC:

Method: POST

Resource: api/arsys/v1/entry/HPD:IncidentInterface_Create?fields=values(Incident Number , Request ID, First_Name)

Payload:

{
  "values": {
    "First_Name": "Allen",
    "Last_Name": "Allbrook",
    "Description": "REST API: Nexthink alert {{alert_config.name}} has been triggered",
    "Impact": "1-Extensive/Widespread",
    "Urgency": "1-Critical",
    "Status": "Assigned",
    "Reported Source": "Direct Input",
    "Service_Type": "User Service Restoration"   
 }
}
CODE

Creating an incident for 4me:

Method: POST

Resource: v1/requests

Payload:

{
"category":"incident",
"subject":"This is a result triggered by the alert {{alert_config.name}}",
"impact":"low",
"service_instance_id":"147488",
"ci":"21819154",
"ci_id":"21819154",
"note":"The alert has been triggered at {{diagnostics.alert.trigger_time}} with the following value {{diagnostics.alerts.trigger_value}}"
}
CODE

Creating a service request for Jira Service Desk:

Method: POST

Resource: rest/servicedeskapi/request

Payload:

{
  "serviceDeskId": "1",
  "requestTypeId": "5",
  "requestFieldValues": {
    "summary": "Request JSD help via REST",
    "description": "I need a new *mouse* for my Mac"
  }
}
CODE

Alerting Tools

Creating an incident for Pager Duty:

Method: POST

Resource: incidents

Payload:

{
  "incident": {
    "type": "incident",
    "title": "api incident for nexthink alert {{alert_config.name}}",
    "service": {
      "id": "PXZF637",
      "summary": null,
      "type": "service_reference",
      "self": null,
      "html_url": null
    },
    "priority": {
      "id": "high",
      "summary": null,
      "type": "priority_reference",
      "self": null,
      "html_url": null
    },
    "urgency": "high",
    "body": {
      "type": "incident_body",
      "details": "string"
    },
    "incident_key": "incident_{{diagnostics.alert.triggered_time}}",
    "escalation_policy": {
      "id": "P14MFQ2",
      "summary": null,
      "type": "escalation_policy_reference",
      "self": null,
      "html_url": null
    },
    "conference_bridge": {
      "conference_number": "string",
      "conference_url": "string"
    }
  }
}
CODE

Messaging Tools

Creating a card in a Teams channel for Microsoft Teams:

Method: POST

Resource: webhookb2/5d4e17ca-3fb8-4799-b1a6-9e393959c4b3@13387b29-82d9-4ca5-9fa0-b7b5635742ef/IncomingWebhook/7465efe12998418d99784436abcbc451/4b9c1496-7e0f-421e-95de-31183103d005

Payload:

{
  "@type": "MessageCard",
  "@context": "http://schema.org/extensions",
  "themeColor": "0076D7",
  "summary": "Critical Alert: {{alert_config.name}} has been raised",
  "sections": [{
      "activityTitle": "Automatic webhook triggered by Nexthink",
      "activitySubtitle": "Critical Alert: {{alert_config.name}} has been raised",
      "activityImage": "https://cdn-assets-cloud.frontify.com/s3/frontify-cloud-files-us/eyJwYXRoIjoiZnJvbnRpZnlcL2FjY291bnRzXC85NFwvMTQwODU2XC9wcm9qZWN0c1wvMTc4MzY0XC9hc3NldHNcLzI2XC8yNTYxMzM1XC8xNGM4NjRmZWNjZDQxODUyOGM3MjhjMDIyMmQyNjA2My0xNTM1MzU5NTQ4LmpwZyJ9:frontify:bu_gT-zWjnzOJ-BvUSZN46o2UWwSKV_CMbv7XZMz7tM?width=626&height={height}",
      "facts": [{
          "name": "Assigned to",
          "value": "Infrastructure Team"
      }, {
          "name": "Effective Date",
          "value": "{{diagnostic.alert.time_triggered}}"
      }, {
          "name": "Status",
          "value": "{{diagnostic.alert .status}}"
      }, {
          "name": "Priority",
          "value": "{{alert_config.priority}}"
      }],
      "markdown": true
  }]
}
CODE

Posting a message on a specific channel for Slack:

Method: POST

Resource: services/T01S01V0HB3/B02GY9BKZ7G/DIDFWXuCAeFfqkgNntQqJV7e

Payload:

{
    "channel":"C01R6KV8CA3",
    "text":"There is an alert {{alert_config.name}} that is affecting the digital experience",
    "attachments":[
        {
         "text":"Who should take a look at it?",
         "fallback":"You could be telling the computer exactly what it can do with a lifetime supply of chocolate.",
         "color":"#3AA3E3",
         "attachment_type":"default",
         "callback_id":"select_simple_1234",
         "actions":[
             {"name":"winners_list",
              "text":"Who should take care of the alert?",
              "type":"select",
              "data_source":"users"
              }
            ]
        }
    ]
}
CODE

Productivity Tools

Creating a bug on a specific project for Jira:

Method: POST

Resource: services/T01S01V0HB3/B02GY9BKZ7G/DIDFWXuCAeFfqkgNntQqJV7e

Payload:

{
   "fields": {
       "project":
       {
          "key": "WHKBUG"
       },
       "summary": "User is experience bad audio quality call",
       "description": "Nexthink alert {{alert_config.name}} has been triggered",
       "issuetype": {
          "name": "Bug"
        },
        "priority":{
            "name": "{{alert_config.priority}}"
        },      
        "timetracking":
        {
           "originalEstimate": "1d 2h",
           "remainingEstimate": "3h 25m"
        }
    }
}
CODE

Data Platforms

Sending an event to the event collector for Splunk:

Method: POST

Resource: services/collector?index=_main

Payload:

{
  "event": "metric",
  "source": "metrics",
  "sourcetype":"perflog",
  "host":"host_2.splunk.com",
  "fields": {
    "region": "us-west-1",
    "datacenter": "dc2",
    "rack": "63",
    "os": "Ubuntu16.10",
    "arch": "x64",
    "team": "LON",
    "service": "6",
    "service_version": "0",
    "service_environment": "test",
    "path": "/dev/sda1",
    "fstype": "ext3",
    "metric_name:cpu.usr": 11.12,
    "metric_name:cpu.sys": 12.23,
    "metric_name:cpu.idle": 13.34
  }
}
CODE