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.
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, ...
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.
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.
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.
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.
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. |
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.