Configuring webhook fields: Method, Resource, and Payload

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

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

• Method

• Resource

• Payload

The following sections explain how to configure the attributes to execute an action on the third-party tool.

Selecting the Method

From the Webhook configuration page, after choosing the credentials:

1. Select one option from the Method dropdown: POST, PUT or PATCH. See the table below.

2. Optionally, review the pertinent third-party software documentation to identify the semantics of each method clearly.

   • Do not assume all methods are similarly used by all vendors and providers of third-party tools.

The REST standard is used over HTTP, comprising a major portion of the uniform interface constraint and provide the request methods available for 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 modification capabilities. The PATCH request only needs to contain the changes to the resource and not the complete resource.

*CRUD is an acronym for create, read, update, and delete.

Filling in the Resource field

Special considerations for resources:

• Resources are data sets accessible via endpoints that can be used with APIs.

• Resources relate to other resources and are limited by the operations that can be carried out on them.

• Resources are presented as endpoint groups based on related data, or the objects they can work with.

• Resources have simple names, making it easy for users to find the right endpoints. However, this may lead to overlooking essential functionality.

To add the Resource value from the Webhook configuration page:

1. Paste the Resource value which is the action specified by the third-party REST API.

   • The URI shouldn’t be added since it is concatenated to the Instance URL defined in the webhook credentials.

   • The Resource value can contain parameters (key=value) that the third-party tool requires.

2. If needed, add placeholders {{variable_name}} to the Resource. Refer to the Using data model variables as placeholders in the payload section on this page.

Examples of valid Resource values

Vendor API URL	Resource value 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>=	v1/requests?api_<token>=

Writing the Payload

The Payload is the data pack sent with the POST/PUT/PATCH method in HTTP.

To write the Paload value from the webhook configuration page:

1. Include in the Payload the crucial information you submit to the server when requesting the API.

   • Optionally, review the pertinent third-party fields and values as the Payload depends on the tool used in the webhook.

2. If needed, use Nexthink data model variables as placeholders {{variable_name}} within the Payload.

   • After filling in the webhook NQL conditions, the system lists the Allowed placeholders in the Nexthink web interface for your convenience.

3. Use the Examples of Method, Resource and Payload from multiple providers included on this page as reference.

The Payload field only accepts JSON format.

Using data model variables as placeholders in the payload

One of the most significant advantages of pushing data from Nexthink into third-party tools is the ability to pass information about an event that has taken place.

To use Nexthink data model variables as placeholders within the Payload:

1. Reference Nexthink variables using the placeholder {{variable_name}} within any field reported in the payload.

2. After filling in the webhook NQL conditions, the webhook configuration page lists the Allowed placeholders in the Nexthink web interface for your convenience.

   • The placeholders in the payload must align with the webhook NQL conditions populating the Nexthink variables.

3. Additionally, you can review the NQL data model to determine the Nexthink variables available for placeholders.

   • Remember, the NQL data model is organized by namespace > table > field.

   • For example, the placeholder {{alert.monitor.name}} contains the name field, from the monitor table, in the alerts namespace. Refer to the Data organization documentation for more information.

4. If needed, use special placeholders not strictly defined in the NQL data model, that are included on this page, and also referenced in the Allowed placeholders in the Nexthink web interface:

   • Special placeholders for alerts data model variables

   • Special placeholders for remote actions model variables

The image below is an example of a payload with placeholders referencing Nexthink data-model variables. Note how the system lists the Allowed placeholders for this case.

The system cannot replace placeholders with empty values or invalid. In these cases, {{variable_name}} appears as is.

Special placeholders for Alerts data model variables

This table includes special placeholders for alerts not strictly defined in the NQL data properties.

Property in NQL data model	Special placeholders
alert.monitor.thresholds	Each array item has an alias (metric name) and a corresponding value: {{alert.monitor.thresholds[n].alias}} {{alert.monitor.thresholds[n].values}} Replace the [n] value with an integer. The number of [n] values depends on the number of metric thresholds defined in the monitor: • [0] value is always available. • [1] or higher values are optional.
alert.trigger_values	Each array item has an alias (metric name) and a corresponding value: {{alert.alert.trigger_values[n].alias}} {{alert.alert.trigger_values[n].value}} Replace the [n] value with an integer: [0] , [1], etc.
alert.trigger_reference_value	{{alert.alert.trigger_reference_value}} Refer to the Metric change item under the Type section in the Customizing built-in monitors documentation to learn more about reference_value computation.
alert.context	{{alert.alert.context}} {{alert.alert.context.<property name>}} {{alert.alert.context.<property name>.label}} {{alert.alert.context.<property name>.data_path}} {{alert.alert.context.<property name>.data_type}} See the examples below*: {{alert.alert.context.binary.name}} {{alert.alert.context.binary.name.label}} {{alert.alert.context.binary.name.data_path}} {{alert.alert.context.binary.name.data_type}} *The context field contains only the data model properties defined in the monitor NQL query and conditions. Therefore, the context field may include the name of the binary, device or user associated with the alert.
alert.alert.issue_view_link alert.alert.device_view_link alert.alerts.links This properties are not currently listed in the NQL data model.	alert.alert.issue_view_link provides the link to the troubleshooting dashboard associated with the alert. You must add the issue_view_link field to the list clause in the webhook NQL condition. alert.alert.device_view_link provides the link provides the link to the Device view. You must add the device_view_link field to the list clause in the webhook NQL condition. Depending on the alert configuration, the alert.alerts.links placeholder provides the link to the Device view or to the troubleshooting dashboard associated with the alert. In this case, you must add both device_view_link and issue_view_linkfields to the list clause in the webhook NQL condition.

Special placeholders for Remote actions data model variables

This table includes special placeholders for remote actions not strictly defined in the NQL data properties.

Property in NQL data model	Special placeholders
remote_action.execution.outputs	{{remote_action.execution.outputs.<property name>}} For example: {{remote_action.execution.outputs.MeteredConnection}}
remote_action.execution.inputs	{{remote_action.execution.inputs.<property name>}} For example: {{remote_action.execution.inputs.InputPath}}
remote_action.execution.account_name This property is not currently listed in the NQL data model.	{{remote_action.execution.account_name}} This placeholder provides the user/employee that executed a remote action.

Examples of Method, Resource and Payload from multiple providers and tools

Refer to the Webhook use cases setup documentation for full webhook configurations for several third-party tools.

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.monitor.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):

{"work_notes": "Remote action {{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:

{
 "impact":"1",
 "urgency":"2",
 "category":"Hardware",
 "short_description":"The alert: {{alert.monitor.name}} has been raised by Nexthink",
 "description":"The Alert {{alert.monitor.name}} has been raised automatically by Nexthink at {{alert.monitor.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:

{
 "values": {
 "First_Name": "Allen",
 "Last_Name": "Allbrook",
 "Description": "REST API: Nexthink alert {{alert.monitor.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:

{
"category":"incident",
"subject":"This is a result triggered by the alert {{alert.monitor.name}}",
"impact":"low",
"service_instance_id":"147488",
"ci":"21819154",
"ci_id":"21819154",
"note":"The alert has been triggered at {{alert.alert.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:

{
 "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:

{
 "incident": {
 "type": "incident",
 "title": "api incident for nexthink alert {{alert.monitor.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.alert.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

Posting a message on an MS Teams channel

Method: POST

Resource: /workflows/XXXXXXXXXXXXXXXXXXX/triggers/manual/paths/invoke?api-version=?????&sp=/triggers/manual/run&sv=1.0&sig=XXXXXXXXXXXXXXX

Payload:

{
    "type": "message",
    "attachments": [
        {
            "contentType": "application/vnd.microsoft.card.adaptive",
            "content": {
                "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
                "type": "AdaptiveCard",
                "version": "1.0",
"msteams": {  
        "width": "Full"  
    },  
                "body": [
                    {
                        "type": "TextBlock",
                        "text": "Nexthink Alert",
                        "id": "Title",
                        "spacing": "Medium",
                        "horizontalAlignment": "Center",
                        "size": "ExtraLarge",
                        "weight": "Bolder",
                        "color": "Accent"
                    },
                    
                    {
            "type": "Container",
            "items": [
                {
                    "type": "TextBlock",
                    "text": "{{alert.alert.context.application.name}},{{alert.monitor.name}}",
                    "wrap": true,
                     "color": "Default",
                    "size": "Medium"
                }
            ],
            "style": "emphasis"
        },
{
                        "type": "FactSet",
                        "facts": [
                            {
                                "title": "Assigned to",
                                "value": "Infrastructure Team"
                            }, {
                               "title": "Triggered on: ",
                               "value": "{{alert.alert.trigger_time}}"
                           },  {
                               "title": "Application Name",
                               "value": "{{alert.alert.context.application.name}}"
                           },

           ]
        },


                     {
            "type": "TextBlock",
            "text": "Condition breached:",
            "wrap": true
        },
        {
            "type": "Table",
            "columns": [
                {
                    "width": 1
                },
                {
                    "width": 1
                },
                {
                    "width": 1
                },
                {
                    "width": 1
                }
            ],
            "rows": [
                {
                    "type": "TableRow",
                    "cells": [
                        {
                            "type": "TableCell",
                            "items": [
                                {
                                    "type": "TextBlock",
                                    "text": "Metric name",
                                    "wrap": true
                                }
                            ]
                        },
                        {
                            "type": "TableCell",
                            "items": [
                                {
                                    "type": "TextBlock",
                                    "text": "Threshold",
                                    "wrap": true
                                }
                            ]
                        },
                        {
                            "type": "TableCell",
                            "items": [
                                {
                                    "type": "TextBlock",
                                    "text": "Metric value",
                                    "wrap": true
                                }
                            ]
                        },
                        {
                            "type": "TableCell",
                            "items": [
                                {
                                    "type": "TextBlock",
                                    "text": "Baseline Value",
                                    "wrap": true
                                }
                            ]
                        }
                    ]
                },
                {
                    "type": "TableRow",
                    "cells": [
                        {
                            "type": "TableCell",
                            "items": [
                                {
                                    "type": "TextBlock",
                                    "text": "{{alert.alert.trigger_values[0].alias}}",
                                    "wrap": true
                                }
                            ]
                        },
                        {
                            "type": "TableCell",
                            "items": [
                                {
                                    "type": "TextBlock",
                                    "text": "{{alert.monitor.thresholds[0].value}}",
                                    "wrap": true
                                }
                            ]
                        },
                        {
                            "type": "TableCell",
                            "items": [
                                {
                                    "type": "TextBlock",
                                    "text": "{{alert.alert.trigger_values[0].value}}",
                                    "wrap": true
                                }
                            ]
                        },
                        {
                            "type": "TableCell",
                            "items": [
                                {
                                    "type": "TextBlock",
                                    "text": "{{alert.alert.trigger_reference_value}}",
                                    "wrap": true
                                }
                            ]
                        }
                    ]
                },
                {
                    "type": "TableRow",
                    "cells": [
                        {
                            "type": "TableCell",
                            "items": [
                                {
                                    "type": "TextBlock",
                                    "text": "{{alert.alert.trigger_values[1].alias}}",
                                    "wrap": true
                                }
                            ]
                        },
                        {
                            "type": "TableCell",
                            "items": [
                                {
                                    "type": "TextBlock",
                                    "text": "{{alert.monitor.thresholds[1].value}}",
                                    "wrap": true
                                }
                            ]
                        },
                        {
                            "type": "TableCell",
                            "items": [
                                {
                                    "type": "TextBlock",
                                    "text": "{{alert.alert.trigger_values[1].value}}",
                                    "wrap": true
                                }
                            ]
                        },
                        {
                            "type": "TableCell",
                            "items": [
                                {
                                    "type": "TextBlock",
                                    "text": "",
                                    "wrap": true
                                }
                            ]
                        }
                    ]
                },
                {
                    "type": "TableRow",
                    "cells": [
                        {
                            "type": "TableCell",
                            "items": [
                                {
                                    "type": "TextBlock",
                                    "text": "",
                                    "wrap": true
                                }
                            ]
                        },
                        {
                            "type": "TableCell",
                            "items": [
                                {
                                    "type": "TextBlock",
                                    "text": "",
                                    "wrap": true
                                }
                            ]
                        },
                        {
                            "type": "TableCell",
                            "items": [
                                {
                                    "type": "TextBlock",
                                    "text": "",
                                    "wrap": true
                                }
                            ]
                        },
                        {
                            "type": "TableCell",
                            "items": [
                                {
                                    "type": "TextBlock",
                                    "text": "",
                                    "wrap": true
                                }
                            ]
                        }
                    ]
                }
            ], "showGridLines": false
        },
        {
            "type": "ActionSet",
            "actions": [
                {
                    "type": "Action.OpenUrl",
                    "title": "View in Nexthink",
                    "URL": "{{alert.alert.issue_view_link}}"
                }
            ]
        }
                ] 
            }
        }
    ]
}

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:

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

Posting a message in Zoom

Method: POST

Resource: chat/webhooks/incomingwebhook/dSUcla-dQaGYgqGuBk3BsQ.

The URL resource above is for illustration purposes only as it depends on the Endpoint URL you directly configure in Zoom.

Payload: Add the message you want to send to Zoom. See the example below.

[
{
"text":"input message",
"img":["file1","file2"]
}
] 

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

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.monitor.name}} has been triggered",
 "issuetype": {
 "name": "Bug"
        },
 "priority":{
 "name": "{{alert.alert.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:

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