Configuring a custom webhook notifier

In addition to sending monitoring alerts via Slack, Pagerduty, and email, you can configure a custom webhook notifier to send alerts through your preferred notification service. When a monitor detects a change in the availability of an endpoint, the IBM® NS1 Connect® platform sends a monitoring alert to each notifier in the notifier list attached to the monitor. If this includes a custom webhook notifier, the platform sends a POST request to the specified webhook URL containing information about the change to the monitor status.

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

Procedure

Configure a webhook notifier using one of the following two methods:

  • Create a new notifier list with a webhook notifier and attach it to a monitor.
  • Add a webhook notifier to a monitor's existing notifier list.
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.

Attention: If you plan to replace a system-generated list, the new list must contain a data feed notifier 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.

  1. Click the User Settings icon and select Notifier lists.
  2. Click Create a notifier list.
  3. Enter a name for the notifier list for internal reference.
  4. Click Add a new notifier.
  5. Click Select notifier type, and select Webhook from the drop-down list.
  6. Enter a webhook URL where NS1 can send a POST request upon changes to the up/down status of a monitored endpoint.
  7. 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 to prevent a malicious actor from spoofing fake notifications. Refer to RFC 9110 for more information about supported HTTP headers and use cases.
  8. 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 optional but strongly recommended as it is 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, then select the __NS1__.data_source.monitoring.0 data source.

    Attention: The data feed notifier is required for the monitor to update answer metadata. Failure to include the data feed notifier will prevent automatic updates.
  9. Add other notifiers to the list you wish to include, and then click Save list & notifiers.
  10. Navigate to the Monitors page and click the monitor's name or click the menu icon to the right of the monitor and select Edit from the list.
  11. Click the Notifications tab.
  12. Click the field under Attach a notifier list and select the list to attach.

    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 notifier later, but you must first save the changes.

  13. Click Save changes.
Option B: Add a webhook notifier to an existing list from the monitor notification settings

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

  1. Navigate to the Monitors page, and click the monitor's name to view its details.
  2. Click the Nofitications tab.

    If the monitor already has a notifier list attached to it, then it appears under Attach to a notifier list.

  3. Click Edit list.
    Attention: 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.
  4. Click Add a new notifier.
  5. From the Select notifier type drop-down list, select Webhook.
  6. Enter a webhook URL where NS1 can send a POST request upon changes to the up/down status of a monitored endpoint.
  7. 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.

  8. Click Save notifier to return to the notifier list settings. The custom webhook notifier appears under Selected notifiers.
    Attention: 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.
  9. Click Save changes.