A notifier list contains one or more channels, called notifiers, through which the NS1 platform will send alerts whenever there are changes to the status of a monitored endpoint. Each monitor probes its assigned endpoint at a certain frequency (e.g., every 60 seconds) from one or more monitoring regions to ensure it meets the defined “up” conditions. If communication with the endpoint fails to meet these conditions, the monitor is considered “down” and alerts are sent to all notifiers in the attached notifier list.
Each notifier list may contain a combination of notifier types, and you can attach the same notifier list to multiple monitors. The types of notifiers you can add to a notifier list include:
-
NS1 data feed
In order for a monitor to update the up/down metadata of its connected answer(s), its notifier list must include the “data feed” notifier. A notifier list with the data feed notifier is automatically generated and attached to a monitor when you create the monitor in the NS1 portal. Note that, if you use the NS1 API to create a monitor, you must create a notifier list with a custom webhook notifier and attach it to the monitor manually.
Warning
Failure to include the data feed notifier in your list will prevent any monitors that use this notifier list from updating answer metadata, breaking automatic failover configurations.
-
Email address
Specify one or more email addresses to receive monitoring alerts.
-
Slack
Using a Slack username and webhook, you can specify a Slack channel or user to receive monitoring alerts. Refer to this article for details.
-
Pagerduty
Using a Pagerduty API key, you can configure up/down monitoring alerts from the NS1 platform delivered via PagerDuty. Refer to this article for details.
-
Webhook notifier
You can configure a custom webhook notifier pointing to your preferred notification service. Upon changes to the monitor status, NS1this article
You can view and manage your notifier lists, including system-generated and custom lists, in the NS1 portal by navigating to the Monitors page and clicking the Notifier lists button. Alternatively, you can click your username in the top right corner of the portal and select Notifer lists from the drop-down menu.
Note
Notifier lists apply only to native NS1 monitors. You cannot attach a notifier list to a data feed generated from a third-party data source. To configure alerts for non-NS1 monitors, you must do so using tools provided by your third-party monitoring service.
After creating an NS1 monitor, you can attach a notifier list containing a list of notifiers (channels) through which to send alerts and adjust the notification settings. Once a monitor detects its endpoint has gone “down,” NS1 waits the notify delay time specified in the notification settings before sending alerts through all the notifiers listed in the notifier list attached to the monitor. NS1 will continue to send repeat alerts indicating the monitored endpoint is still “down” at a frequency defined by the notify repeat setting until the monitor status returns to “up.” If enabled in the monitor’s notification settings, NS1 will send one final alert to all notifiers indicating the monitored endpoint is back up.
When you create an NS1 monitor in the NS1 portal, a notifier list containing the data feed notifier is automatically created and attached to the monitor. The data feed notifier is required in order for the monitor to update the up/down metadata for its connected answer(s).
Note
If you create a monitor via API, you must create a notifier list with, at least, the data feed notifier and attach it to the monitor manually in subsequent API requests.
You can edit the monitor’s notifier list to include additional notifiers (email, Slack, etc.) or replace the list with a custom notifier list you create. The latter may be preferred if you want to use the same notifiers for multiple monitors. Whether you choose to edit the monitor’s auto-generated list or create a new one, the list must include a “data feed” notifier in order for automatic updates to work as expected.
Warning
If a monitor is being used for automatic updates to answer metadata, the notifier list attached to that monitor must include a “data feed” notifier. System-generated notifier lists already include the data feed notifier. If you edit or replace the system-generated list created for a monitor, you must ensure the new or updated list includes the data feed notifier in order for automatic updates to occur.
If you want to use the same notifiers for multiple monitors, you can create or edit a custom notifier list and attach it to all applicable monitors. This approach makes it easy to view and manage your monitoring alerts in one place as opposed to having to maintain multiple, identical notifier lists for each monitor.
Alternatively, you can edit a system-generated list to include additional notifiers for a single monitor.
-
In the portal, click your username in the upper right corner and select Notifier lists from the drop-down menu.
The Notifier lists page contains all notifier lists. If you previously connected a monitor to a DNS answer, the system-generated notifier list(s) will appear here.
-
Click Create a notifier list.
-
Enter a name for the list (for internal reference only).
-
Under Available notifiers, you may see one or more notifiers listed already. You can add available notifiers to this list by clicking the plus sign (+) next to it. For example, the data feed notifier (__NS1__.data_source_monitoring.0) will appear if you have created at least one monitor. We strongly recommend that you include the data feed notifier in ever notifier list you create or modify as it is the mechanism used to update answer metadata connected to the monitors.
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 and, potentially, steer your DNS traffic toward unavailable endpoints.
-
Click Add a new notifier to specify a new channel for monitoring alerts.
-
Click Select notifier type, and select one of the following notifiers from the list:
-
NSONE Data Feed
If selected, you must also select the NS1 data source, as shown below.
Warning
You must include the data feed notifier in order for the monitor to update answer metadata which is critical for automatic failover configurations.
-
Email
If selected, enter an email address to receive monitoring alerts.
-
Pagerduty
If selected, enter a valid Pagerduty API key. Refer to this article for details.
-
Slack
If selected, enter a Slack username, a webhook URL, and a user or channel to receive alerts. Refer to this article for details.
-
Webhook
If selected, enter the custom webhook URL and, optionally, one or more HTTP headers. Refer to this article to learn more about using a custom webhook notifier.
-
-
Repeat the previous step for each notifier you want to include in this list.
-
Once complete, click Save list and notifiers. The new notifier list appears in the list (note that you might need to refresh the page). Next, you must attach the list to one or more monitors.
-
Navigate to the Monitors page.
-
Click the name of the monitor to view its details. (Or, you can click the menu icon next to the monitor and select Edit from the dropdown.)
-
Click the Notifications tab.
-
Click the dropdown menu under Attach to a notifier list to view all notifier lists. Select the notifier list you just created.
-
Optionally, adjust the notification settings for this monitor, including:
-
Notify delay - In the event that the monitor detects the endpoint is down, enter the amount of time (in seconds) NS1 should wait before sending alerts. A value of 0 indicates that an alert should be sent immediately once the monitor detects a “down” status.
-
Notify repeat - If desired, NS1 can continue sending alerts at a specified frequency to remind you that the monitored endpoint is still considered “down.” Enter the amount of time (in seconds) between these repeat notifications. Repeat notifications will cease once the monitor detects the endpoint is back up. A value of 0 disables repeat notifications.
-
Notify failback - Enable this option to receive a notification once the monitor detects the endpoint is back up (i.e., meets the monitor’s “up” conditions).
-
Notify regional - Enable this option to receive a notification if any of the selected monitoring regions fail to connect (at all or within a specified time) with the monitored endpoint. Note that, depending on the “up conditions” defined in the monitor settings, it’s possible that one or more regions can detect a failure without the monitor being considered down.
-
-
Click Save changes.
-
Repeat steps 9-14 for each monitor to which you want to attach the custom notifier list.
When you create a monitor in the NS1 portal, a notifier list containing the data feed notifier is automatically created and attached to the monitor. You can edit a monitor’s auto-generated list or any custom list you previously attached to a monitor from within the monitor’s Notifications tab.
-
Navigate to the Monitors page.
-
Click the name of the monitor to view its details. (Or, you can click the menu icon next to the monitor and select Edit from the dropdown.)
-
Click the Notifications tab.
The name of the notifier list attached to the monitor appears under Attach to a notifier list. System-generated lists appear as __NS1__.notify_list.#.
-
Click Edit list.
-
Add new notifiers as desired, but do not remove the data feed notifier as this will prevent the monitor from making automatic updates to connected answers. (Refer to the previous section for descriptions and requirements for each type of notifier.)
-
Once complete, click Save changes.
The format of the PUT request below can be used to create a new notifier list with one or more notifiers. The config options for each notifier vary depending on the notifier type.
curl -X PUT -H "X-NSONE-Key: $NSONE_API_KEY" -d
'{
"name": "string",
"notify_list": [
{
"type": "",
"config": {
}
},
{
"type": "",
"config": {
}
}
}
]
}' https://api.nsone.net/v1/list
Table 1. Request body parameters
|
name |
string |
(Required) Name of the notifier list |
|
notify_list |
array of objects |
(Required) Container for the list of notifiers and the configuration details for each |
|
type |
string (enum) |
Indicates the type of notifier you are including in this list. Supported values include: "datafeed", "webhook", "email", "slack", "pagerduty" |
|
config |
object |
Contains one or more configuration options pertaining to the notifier. Options and format vary depending on the notifier type. Refer to the example below to see the config options and structure for each notifier type. |
Example request:
curl -X PUT -H "X-NSONE-Key: $NSONE_API_KEY" -d
'{
"name": "My example notifier list",
"notify_list": [
{
"type": "datafeed",
"config": {
"sourceid": "ace52bc1f4e042bc790c756ee2121b75"
}
},
{
"type": "webhook",
"config": {
"url": "https://example.webhook.com",
"headers": {
"Authorization": "Basic ZGVtbzpwQDU1dzByZA=="
}
}
},
{
"type": "email",
"config": {
"email": "notify@example.com"
}
},
{
"type": "pagerduty",
"config": {
"service_key": "ExAmPlEpAgErDuTyApIkEy"
}
}
]
}' https://api.nsone.net/v1/list
If successful, the response includes a unique ID assigned to this notifier list as well as a reiteration of the notifier list's configuration details.
{
"id": "64a83057987fd60080cacaec",
"name": "My example notifier list",
"notify_list": [
...
The notifier list ID is required for API requests to view details for this specific notifier list.
Note
Refer to the NS1 API documentation for a complete index of API endpoints and requests, including those related to monitors and notifier lists.