Using alerts

In this section, learn how to use alerts, including adding an alert, getting list of your alerts, and deleting an alert.

Add an alert

To add an alert, make the following POST request with the request parameters:

Name	Type	Required or Optional	Description
name	string	Required	Name of your alert.
type	string	Required	Type of the metric to monitor: iNode Status (NODE_STATE_CHANGE), Remote Network Connection Status (TUNNEL_STATE_CHANGE), Service Status (SERVICE_STATE_CHANGE), iNode Certificate Expiry (CERT_EXPIRY), Standalone Mode Expiry (HEADLESS_EXPIRY), iNode IP Address Change (NODE_IP_CHANGE), or iNode Upgrade Status (NODE_UPGRADE).
settings	object	Required	Settings for: the metric’s value to compare with, the duration for the alert condition to be true (for NODE_STATE_CHANGE, TUNNEL_STATE_CHANGE, SERVICE_STATE_CHANGE, or NODE_IP_CHANGE only), and the target resource whose condition you want to evaluate.
channel_type	string	Optional	How to notify you when the alert is triggered: email or webhook.
channel_id	string	Optional	For webhook notification, specify your webhook ID. Ignore this parameter for email notification.

Following is an example to add an alert with webhook notification when the iNode Status has been ALIVE or UNREACHABLE for a duration of five minutes for all nodes in your organization.

curl -X POST \
  -H 'X-API-KEY:<your_api_key>' \
  -H "Content-type:application/json" \
  -d '{"name":"<your_alert_1_name>", \
       "type":"NODE_STATE_CHANGE" \
       "settings":{ \
         "org_id":"<your_org_id>",  \
         "alert_me":"ALIVE,UNREACHABLE", \
         "duration":5 \
       }, \
       "channel_type":"webhook", \
       "channel_id":"<your_webhook_id>" \
      }' \
'https://<your_company>.manage.iotium.io/api/v1/mysubscriptions/'

When successful, the response includes details of the alert:

{
    "metadata":{
      "labels":{
        "_iotium.alert.name":"Node Status Alert"
      }
    },
    "name":"<your_alert_1_name>",
    "type":"NODE_STATE_CHANGE",
    "settings":{
      "org_id":"<your_org_id>",
      "include_child":"true",
      "alert_me":"ALIVE,UNREACHABLE",
      "duration":"5"
    },
    "id":"<your_alert_1_id>",
    "display_type":"iNode Status",
    "channel_type":"WEBHOOK",
    "channel":
     {
        "id":"<your_webhook_id>"
        "name":"<your_webhook_name>"
     },
    "created_at":"2019-08-27T01:43:39.541-06:00",
    "created_by":{
      "id":"<your_user_id>",
      "name":"<your_user_name>"
    }
}

If the webhook has been disabled, the error response is as follows:

{
  "statusCode": 422,
  "errorCode": "UNPROCESSABLE_ENTITY",
  "message": "The given webhook is in disabled state. So can't  associate with alert subscription."
}

You may add maximum of 10 alert notifications using webhooks.

This is an example to add an alert with email notification when iNode Status has been ALIVE or UNREACHABLE for a duration of five minutes for all nodes in your organization:

curl -X POST \
  -H 'X-API-KEY:<your_api_key>' \
  -H "Content-type:application/json" \
  -d '{"name":"<your_alert_2_name>", \
       "type":"NODE_STATE_CHANGE" \
       "settings":{ \
         "org_id":"<your_org_id>",  \
         "alert_me":"ALIVE,UNREACHABLE", \
         "duration":5 \
       }, \
       "channel_type":"email" \
      }' \
'https://<your_company>.manage.iotium.io/api/v1/mysubscriptions/'

When successful, the response includes details of the alert:

{
    "metadata":{
      "labels":{
        "_iotium.alert.name":"Node Status Alert"
      }
    },
    "name":"<your_alert_2_name>",
    "type":"NODE_STATE_CHANGE",
    "settings":{
      "org_id":"<your_org_id>",
      "include_child":"true",
      "alert_me":"ALIVE,UNREACHABLE",
      "duration":"5"
    },
    "id":"<your_alert_2_id>",
    "display_type":"iNode Status",
    "channel_type":"EMAIL",
    "channel":
     {
        "id":"<your_email_resource_id>"
        "name":"Email"
     },
    "created_at":"2019-08-27T01:43:39.541-06:00",
    "created_by":{
      "id":"<your_user_id>",
      "name":"<your_user_name>"
    }
}

Get a list of alerts

To get the list of your alerts, make the following GET request:

curl -X GET \
  -H 'X-API-KEY:<your_api_key>' \
  -H "Content-type:application/json" \
'https://<your_company>.manage.iotium.io/api/v2/mysubscriptions'

The response includes details of all your alerts:

{
  "results": [
    {
      "metadata": {
        "labels": {
          "_iotium.alert.name": "Node Status Alert"
        }
      },
      "name": "<your_alert_1_name>",
      "type": "NODE_STATE_CHANGE",
      "settings": {
        "org_id": "<your_org_id>",
        "include_child": "true",
        "alert_me": "ALIVE,UNREACHABLE",
        "duration": "5"
      },
      "id": "<your_alert_1_id>",
      "display_type": "iNode Status",
      "channel_type": "WEBHOOK",
      "channel": {
        "id": "<your_webhook_id>",
        "name": "<your_webhook_name>"
      },
      "created_at": "2019-08-27T01:43:39.541-06:00",
      "created_by": {
        "id": "<your_user_id>",
        "name": "<your_user_name>"
      }
    },
    {
      "metadata": {
        "labels": {
          "_iotium.alert.name": "Node Status Alert"
        }
      },
      "name": "<your_alert_2_name>",
      "type": "NODE_STATE_CHANGE",
      "settings": {
        "org_id": "<your_org_id>",
        "include_child": "true",
        "alert_me": "ALIVE,UNREACHABLE",
        "duration": "5"
      },
      "id": "<your_alert_2_id>",
      "display_type": "iNode Status",
      "channel_type": "EMAIL",
      "channel": {
        "id": "<your_email_resource_id>",
        "name": "Email"
      },
      "created_at": "2019-08-27T01:43:39.541-06:00",
      "created_by": {
        "id": "<your_user_id>",
        "name": "<your_user_name>"
      }
    }
  ]
}

To get the details of a specific alert, make the following GET request:

curl -X GET \
  -H 'X-API-KEY:<your_api_key>' \
  -H "Content-type:application/json" \
'https://<your_company>.manage.iotium.io/api/v1/mysubscriptions/<your_alert_1_id>'

The response includes details of the first alert we added above:

{
    "metadata":{
      "labels":{
        "_iotium.alert.name":"Node Status Alert"
      }
    },
    "name":"<your_alert_1_name>",
    "type":"NODE_STATE_CHANGE",
    "settings":{
      "org_id":"<your_org_id>",
      "include_child":"true",
      "alert_me":"ALIVE,UNREACHABLE",
      "duration":"5"
    },
    "id":"<your_alert_1_id>",
    "display_type":"iNode Status",
    "channel_type":"WEBHOOK",
    "channel":
     {
        "id":"<your_webhook_id>"
        "name":"<your_webhook_name>"
     },
    "created_at":"2019-08-27T01:43:39.541-06:00",
    "created_by":{
      "id":"<your_user_id>",
      "name":"<your_user_name>"
    }
}

Delete an alert

To delete an alert, make the following DELETE request:

curl -X DELETE \
  -H 'X-API-KEY:<your_api_key>' \
  -H "Content-type:application/json" \
'https://<your_company>.manage.iotium.io/api/v1/mysubscriptions/<your_alert_id>'

The response includes the following information:

{
  "id": "<your_alert_id>",
  "message": "Successfully deleted.",
  "status": "SUCCESS"
}