Custom webhook notifiers – NS1 Help Center

There are multiple channels through which you can send monitoring-related alerts from the NS1 platform — including email, Slack, and Pagerduty. Alternatively, you can use a custom webhook notifier to enable alerts through your preferred notification service.

How it works

When an NS1 monitor detects a change in the availability of an endpoint, NS1 sends alerts through each notifier listed in the notifier list attached to the monitor. If the list includes a custom webhook notifier, a POST request is sent to the specified webhook URL. The request contains information about the monitor, including its updated status — either “up” or “down”.

For example, if a PING monitor detects an endpoint is down, an alert (in the form of a POST request) sent to the webhook URL might look something like this:

{
  "state": "down",
  "since": 1444744828,
  "region": "global",
  "job": {
    "notes": null,
    "name": "ping2",
    "notify_repeat": 0,
    "id": "561d0d482db1564c88776b57",
    "region_scope": "fixed",
    "rapid_recheck": false,
    "frequency": 60,
    "job_type": "ping",
    "notify_delay": 0,
    "notify_list": "560d7d249f782d4d663d7d3d",
    "notify_regional": false,
    "regions": [
      "lga"
    ],
    "policy": "quorum",
    "config": {
      "timeout": 2000,
      "host": "1.1.1.1",
      "count": 4
    },
    "status": {
      "global": {
        "since": 1444744580,
        "status": "up"
      },
      "lga": {
        "since": 1444744580,
        "status": "up"
      }
    },
    "notify_failback": true,
    "rules": [],
    "active": true
  }
}

When the monitor detects the endpoint is available again, another alert is sent with the “state” of the monitor returned to “up.”

{
  "state": "up",
  "since": 1444745000,
...

Instructions

You can add a webhook notifier to a new or existing notifier list, either from the Notifier lists page or from an individual monitor’s notification settings.

Option A: Create a new notifier list with a webhook notifier & attach it to a monitor

If you plan to use the same webhook notifier (and/or other notifiers) for more than one monitor, you can create a new notifier list and attach it to multiple monitors.

Warning

If you plan to replace a system-generated list, the new list must contain a data feed notifier in order for the monitor(s) to update answer metadata.

Follow the instructions below to create a new notifier list with a custom webhook notifier, and then attach it to an NS1 monitor.

In the NS1 portal, click your username in the top right corner and select Notifier lists from the drop-down menu.

The Notifier lists shows you all existing notifier lists, including system-generated lists (e.g., notify_list.#) created by NS1 automatically when you configure an NS1 monitor via the portal. System-generated lists already contain the "data feed" notifier which is required for the monitor to update answer metadata.
Click Create a notifier list.
Enter a name for the notifier list (for internal reference).
Click Add a new notifier.
Click Select notifier type, and select Webhook from the dropdown.
Enter a webhook URL where NS1 will send a POST request upon changes to the up/down status of a monitored endpoint.
Optionally, click + Webhook headers to add an HTTP header (key-value pair) to include in the POST request to the specified URL. Each header must use a unique key. Headers can be used for authenticating notifications from the NS1 platform in order to prevent a malicious actor from spoofing fake notifications. Refer to RFC 9110 for more information about supported HTTP headers and use cases.
If shown under Available notifiers, click the plus sign (+) next to __NS1__.data_source.monitoring.0 to include the data feed notifier in this list. This is technically optional, but strongly recommended as it required for monitors to update answer metadata.

If you do not see this notifier listed, click Add a new notifier. Select NSONE Data Feed as the notifier type, and then select the __NS1__.data_source.monitoring.0 data source.

Warning

The data feed notifier is required for the monitor to update answer metadata. Failure to include the data feed notifier will prevent automatic updates.
Add other notifiers to the list you wish to include, and then click Save list & notifiers.
Next, you must attach the notifier list to the monitor(s). Navigate to the Monitors page and click the name of the monitor to view its details. (Alternatively, you can click the menu icon (three dots) to the right of the monitor and select Edit from the list.)
Click the Notifications tab.
Click the field under Attach a notifier list and select the custom list you just created. Note that this is not to be confused with clicking Edit list which allows you to make changes to the current notifier list, if applicable, as opposed to attaching a new one to the monitor.

If you did not include a data feed notifier in the new list, you might see a warning message letting you know that, without a data feed notifier, the monitor cannot automatically update answer metadata.

Click I understand. You can edit the new notifier list to include the data feed otifier later, but you must first save the changes.
Click Save changes to update the notifier list assigned to the monitor.

Option B: Add a webhook notifier to an existing list from the monitor notification settings

If you want to add a custom webhook notifier to an existing list that is already attached to a monitor, such as a system-generated list or a custom list you applied previously, you can do so from within the monitor’s notification settings.

Navigate to the Monitors page, and click the name of the monitor to view its details.
Click the Notifications tab.

If the monitor already has a notifier list attached to it, then it will appear under Attach to a notifier list.
Click the Edit list button next to the name of the notifier list. The Edit notifier list modal appears.

Warning

Do not delete the data feed notifier from the list. Doing so prevents the monitor from automatically updating the connected answer metadata which may result in your application users being directed to unavailable endpoints.
Click Add a new notifier.
Under Select notifier type, select Webhook.
Enter a webhook URL where NS1 will send a POST request upon changes to the up/down status of a monitored endpoint.
Optionally, click + Webhook headers to add an HTTP header (key-value pair) to pass along with the POST request to the specified URL. Each header must use a unique key.

As an example, headers can be used for authenticating notifications from the NS1 platform in order to prevent a malicious actor from spoofing fake notifications. Refer to RFC 9110 for more information about supported HTTP headers and use cases.
Click Save notifier to return to the notifier list settings. You can see the custom webhook notifier appears under Selected notifiers.

Warning

Do not delete the data feed notifier from the list. Doing so prevents the monitor from automatically updating the connected answer metadata which may result in your application users being directed to unavailable endpoints.
Click Save changes.

API reference: Custom webhook notifier

You can use the NS1 API to add a custom webhook notifier to a new or existing notifier list. Note that you must also attach the notifier list to one or more monitors in order to enable alerts through the webhook upon changes to the monitored endpoint’s up/down status.

The webhook object

When creating or updating a notifier list via API, the notify_list array contains a list of notifiers through which to send monitoring alerts. The example below demonstrates the format of the custom webhook notifier object to include in the list of notifiers.

{
   "type": "webhook",
   "config": {
      "url": "string",
      "headers": {
         "key": "value"
      }
   }
}

type	string (enum)	Type of notifier you are adding to the notifier list. "webhook" indicates a custom webhook notifier.
config	object	An object containing configuration settings for this notifier. Configuration options vary based on the notifier type.
url	string	(If webhook notifier) Webhook URL to which NS1 will send POST requests upon changes to the monitor status.
headers	object	(Optional; if webhook notifier) An object containing one or more key-value pairs representing HTTP header(s) to include in the POST request from NS1 to the webhook URL. Each header must use a unique "key." Refer to RFC 9110 for more information about supported HTTP headers and use cases.

Create a notifier list with a custom webhook (via API)

URL path:

/v1/lists

The PUT request below demonstrates the format for creating a new notifier list with a custom webhook notifier and the data feed notifier which is strongly recommended for any notifier list.

curl -X PUT -H 'X-NSONE-Key: $NSONE_API_KEY' -d 
'{
  "name": "string",
  "notify_list": [
    {
      "type": "webhook",
      "config": {
        "url": "string",
        "headers": {
           "key": "value"
        }
      }
    },
    {
      "type": "datafeed",
      "config": {
        "sourceid": "string"
      }
    }
  ]
}' https://api.nsone.net/v1/lists

In addition to the webhook parameters, you must also include a name for the notifier list you are creating.

Example: Create a notifier list with a basic webhook notifier

The example below creates a new notifier list with a custom webhook notifier (without HTTP headers) and a data feed notifier which is required in order for monitors to update answer metadata.

curl -X PUT -H 'X-NSONE-Key: $NSONE_API_KEY' -d 
'{
  "name": "Example notifier list",
  "notify_list": [
    {
      "type": "webhook",
      "config": {
        "url": "https://example.webhook.com"
      }
    },
    {
      "type": "datafeed",
      "config": {
        "sourceid": "ace52bc1f4e042bc790c756ee2121b75"
      }
    }
  ]
}' https://api.nsone.net/v1/lists

Example: Create a notifier list with a webhook notifier with HTTP header for authenticating monitoring alerts

The example below creates a new notifier list with a custom webhook notifier that includes one HTTP header for authentication. The list also includes the data feed notifier which we recommend you include for all notifier lists. Note that you can specify multiple HTTP headers using a comma to separate each key-value pair.

curl -X PUT -H 'X-NSONE-Key: $NSONE_API_KEY' -d 
'{
  "name": "Example notifier list",
  "notify_list": [
    {
      "type": "webhook",
      "config": {
        "url": "https://example.webhook.com",
        "headers": {
            "Authorization": "Basic ZGVtbzpwQDU1dzByZA=="
        }
      }
    },
    {
      "type": "datafeed",
      "config": {
        "sourceid": "ace52bc1f4e042bc790c756ee2121b75"
      }
    }
  ]
}' https://api.nsone.net/v1/lists

Note

Refer to the NS1 API documentation for a complete index of API endpoints and requests, including those for managing monitoring notifier lists and notifiers.

Articles in this section

How it works

Instructions

Option A: Create a new notifier list with a webhook notifier & attach it to a monitor

Warning

Warning

Option B: Add a webhook notifier to an existing list from the monitor notification settings

Warning

Warning

API reference: Custom webhook notifier

The webhook object

Create a notifier list with a custom webhook (via API)

Note

Related articles