Skip to main content
Skip table of contents

Method, resource, and payload

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

The following sections 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.

The table below shows a list of supported methods:

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 modification 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 is 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, to understand the semantics of each method clearly.

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 based on related data or the objects they are allowed to work with. They have simple names, making it easy for users to find the right endpoints. However, this may lead to overlooking essential functionality.

The value in the Resource is the action 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

https://api.4me.com/v1/requests?api_token=<token>

v1/requests?api_token=<token>

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 most significant advantages of pushing 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 reported in the payload.

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

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

Refer to the NQL data model documentation for more information on data model variables.

Examples from multiple providers and vendors

ITSM Tools

Creating an incident for ServiceNow

Method: POST

Resource: api/now/v1/table/incident

Payload:

CODE
{
    "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.monitors.name}}",
    "sys_created_by":"Nexthink Integration test David G.",
    "urgency":4
}

Follow this guideline to set up webhooks to detect alerts and events and transmit them to ServiceNow to create an incident.

Updating ServiceNow incident ticket from Amplify

Method: PATCH

Resource: api/now/v1/table/incident/{{remote_action.execution.external_reference}}

Payload (message):

CODE
{
"work_notes": "Remote action {{remote_action.name}} was triggered for this ticket from Amplify user {{remote_action.execution.account_name}}
at {{remote_action.execution.request_time}}"
}

Follow this guideline to set up webhooks to update ServiceNow executed actions log from Amplify.

Creating a problem for ServiceNow

Method: POST

Resource: api/now/v1/table/problem

Payload:

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

Creating an incident for BMC

Method: POST

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

Payload:

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

Creating an incident for 4me

Method: POST

Resource: v1/requests

Payload:

CODE
{
"category":"incident",
"subject":"This is a result triggered by the alert {{alert.monitors.name}}",
"impact":"low",
"service_instance_id":"147488",
"ci":"21819154",
"ci_id":"21819154",
"note":"The alert has been triggered at {{alert.alerts.trigger_time}} with the following values: {{alert.alerts.trigger_values[0].alias}}: {{alert.alerts.trigger_values[0].value}}, {{alert.alerts.trigger_values[1].alias}}: {{alert.alerts.trigger_values[1].value}}"
}

Creating a service request for Jira Service Desk

Method: POST

Resource: rest/servicedeskapi/request

Payload:

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

Alerting Tools

Creating an incident for Pager Duty

Method: POST

Resource: incidents

Payload:

CODE
{
  "incident": {
    "type": "incident",
    "title": "api incident for nexthink alert {{alert.monitors.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_{{alert.alerts.trigger_time}}",
    "escalation_policy": {
      "id": "P14MFQ2",
      "summary": null,
      "type": "escalation_policy_reference",
      "self": null,
      "html_url": null
    },
    "conference_bridge": {
      "conference_number": "string",
      "conference_url": "string"
    }
  }
}

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:

CODE
{
  "@type": "MessageCard",
  "@context": "http://schema.org/extensions",
  "themeColor": "0076D7",
  "summary": "Critical Alert: {{alert.monitors.name}} has been raised",
  "sections": [{
      "activityTitle": "Automatic webhook triggered by Nexthink",
      "activitySubtitle": "Critical Alert: {{alert.monitors.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": "{{alert.alerts.trigger_time}}"
      }, {
          "name": "Status",
          "value": "{{alert.alerts.status}}"
      }, {
          "name": "Priority",
          "value": "{{alert.alerts.priority}}"
      }, {
          "name": "{{alert.monitors.thresholds[0].alias}}",
          "value": "{{alert.monitors.thresholds[0].value}}"
      }, {
          "name": "{{alert.monitors.thresholds[1].alias}}",
          "value": "{{alert.monitors.thresholds[1].value}}"
      }],
      "markdown": true
  }]
}

Follow this guideline to set up MS Teams to receive incoming requests.

Posting a message on a specific channel for Slack

Method: POST

Resource: services/T01S01V0HB3/B02GY9BKZ7G/DIDFWXuCAeFfqkgNntQqJV7e

Payload:

CODE
{
    "channel":"C01R6KV8CA3",
    "text":"There is an alert {{alert.monitors.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"
              }
            ]
        }
    ]
}

Follow this guideline to set up Slack to receive incoming requests.

Productivity Tools

Creating a bug on a specific project for Jira

Method: POST

Resource: services/T01S01V0HB3/B02GY9BKZ7G/DIDFWXuCAeFfqkgNntQqJV7e

Payload:

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

Data Platforms

Sending an event to the event collector for Splunk

Method: POST

Resource: services/collector?index=_main

Payload:

CODE
{
  "event": "metric",
  "source": "metrics",
  "sourcetype":"perflog",
  "fields": {
    "event_name":"System crash",
    "event_number_of_system_crashes":"{{device_performance.system_crashes.number_of_system_crashes}}",
    "event_label":"{{device_performance.system_crashes.label}}",
    "event_error_code":"{{device_performance.system_crashes.error_code}}",
    "event_time":"{{device_performance.system_crashes.time}}",
    "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"
  }
}

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.