5.9. Notifications

A notification is a destination to send an alarm, it can be a variety of different types, and will evolve over time.

For instance, with a webhook type notification Rackspace Cloud Monitoring posts JSON formatted data to a user-specified URL on an alert condition (Check goes from OK -> CRITICAL and so on).

A notification, ntTechnicalContactsEmail, is provided by default which will email all of the technical contacts on file for an account. It can be used to create a notification plan just as a normal notification would be used and will only alert the technical contacts on state changes as defined in the notification plan.

Table 5.7. Attributes
NameDescriptionValidation
details A hash of notification specific details based on the notification type.
  • Hash [String,String between 1 and 255 characters long:Non-empty string,String between 1 and 4096 characters long]

  • Array or object with number of items between 0 and 256

label Friendly name for the notification.
  • String between 1 and 255 characters long

type The notification type to send.
  • String

  • One of (webhook, email, pagerduty, sms, managed, technicalContactsEmail, atomHopper)

metadata Arbitrary key/value pairs.
  • Optional

  • Hash [String,String between 1 and 255 characters long:String,String between 1 and 255 characters long]

  • Array or object with number of items between 0 and 256

Use the notifications API operations to create, view, and manage notifications.

MethodURIDescription
POST/notifications

Creates a notification.

POST/notifications/test-notification

Test a notification.

GET/notifications

Lists the notifications for the account.

POST/notifications/{notificationId}/test

Tests an existing notification.

GET/notifications/{notificationId}

Returns information about the specified notification.

PUT/notifications/{notificationId}

Updates the specified notification with update attribute values submitted with the request.

DELETE/notifications/{notificationId}

Deletes a notification from the user account.

 5.9.1. Create a notification

 
MethodURIDescription
POST/notifications

Creates a notification.

Create a new notification in the monitoring system by using a valid set of attributes from the Notifications Attributes table.

This table shows the possible response codes for this operation:

Response CodeNameDescription
201Accepted

'Location' header contains a link to the newly created check.

400Bad request

The system received an invalid value in a request.

401Unauthorized

The system received a request from a user that is not authenticated.

403Forbidden

The system received a request that the user is not authorized to make.

500Internal Server Error

An unexpected condition was encountered.

503Service Unavailable

The system is experiencing heavy load or another system failure.

 5.9.1.1. Request

This table shows the header parameters for the create a notification request:

NameTypeDescription

X-Auth-Token

​String

(Required)

A valid authentication token with administrative access.

 

Example 5.53. Create webhook notification: XML request

<?xml version="1.0" encoding="utf-8"?>
<notification>
  <label>my webhook #1</label>
  <type>webhook</type>
  <details>
    <url>https://systems.example.org/alert</url>
  </details>
</notification>

 

Example 5.54. Create webhook notification: JSON request

{
    "label": "my webhook #1",
    "type": "webhook",
    "details": {
        "url": "https://systems.example.org/alert"
    }
}

 

Example 5.55. Create email notification: XML request

<?xml version="1.0" encoding="utf-8"?>
<notification>
  <label>my email #1</label>
  <type>email</type>
  <details>
    <address>test@example.com</address>
  </details>
</notification>

 

Example 5.56. Create email notification: JSON request

{
    "label": "my email #1",
    "type": "email",
    "details": {
        "address": "test@example.com"
    }
}

 5.9.2. Test a notification

 
MethodURIDescription
POST/notifications/test-notification

Test a notification.

This operation allows you to test a notification before creating it. The actual notification comes from the same server where the actual alert messages come from. This allow you to, among other things, verify that your firewall is configured properly.

This table shows the possible response codes for this operation:

Response CodeNameDescription
200OK

Request completed.

400Bad request

The system received an invalid value in a request.

401Unauthorized

The system received a request from a user that is not authenticated.

403Forbidden

The system received a request that the user is not authorized to make.

500Internal Server Error

An unexpected condition was encountered.

503Service Unavailable

The system is experiencing heavy load or another system failure.

 5.9.2.1. Request

This table shows the header parameters for the test a notification request:

NameTypeDescription

X-Auth-Token

​String

(Required)

A valid authentication token with administrative access.

 

Example 5.57. Test notification: XML request

<?xml version="1.0" encoding="utf-8"?>
<test_notification>
  <type>webhook</type>
  <details>
    <url>http://my.web-server.com:5981/</url>
  </details>
</test_notification>

 

Example 5.58. Test a notification: JSON request

{
    "type": "webhook",
    "details": {
        "url": "http://my.web-server.com:5981/"
    }
}

 5.9.2.2. Response

 

Example 5.59. Test a notification: XML response

<?xml version="1.0" encoding="utf-8"?>
<notification_data>
  <status>success</status>
  <message>Success: Webhook successfully executed</message>
</notification_data>

 

Example 5.60. Test a notification: JSON response

{
    "status": "success",
    "message": "Success: Webhook successfully executed"
}

 5.9.3. List Notifications

 
MethodURIDescription
GET/notifications

Lists the notifications for the account.

This operation can be paginated. For information, see Paginated collections

This table shows the possible response codes for this operation:

Response CodeNameDescription
200OK

The request completed.

401Unauthorized

The system received a request from a user that is not authenticated.

403Forbidden

The system received a request that the user is not authorized to make.

500Internal Server Error

An unexpected condition was encountered.

503Service Unavailable

The system is experiencing heavy load or another system failure.

 5.9.3.1. Request

This table shows the header parameters for the list notifications request:

NameTypeDescription

X-Auth-Token

​String

(Required)

A valid authentication token with administrative access.

This operation does not accept a request body.

 5.9.3.2. Response

 

Example 5.61. List notifications: XML response

<?xml version="1.0" encoding="utf-8"?>
<container>
  <values>
    <notification id="ntAAAA">
      <label>my webhook #1</label>
      <type>webhook</type>
      <details>
        <url>https://systems.example.org/alert</url>
      </details>
    </notification>
  </values>
  <metadata>
    <count>1</count>
    <limit>50</limit>
    <marker/>
    <next_marker/>
    <next_href/>
  </metadata>
</container>

 

Example 5.62. List notifications: JSON response

{
    "values": [
        {
            "id": "ntAAAA",
            "label": "my webhook #1",
            "type": "webhook",
            "details": {
                "url": "https://systems.example.org/alert"
            }
        }
    ],
    "metadata": {
        "count": 1,
        "limit": 50,
        "marker": null,
        "next_marker": null,
        "next_href": null
    }
}

 5.9.4. Test an existing notification

 
MethodURIDescription
POST/notifications/{notificationId}/test

Tests an existing notification.

This operation allows you to test an existing notification. The notification comes from the same server that the alert messages come from. One use for this test is to verify that your firewall is configured properly.

This table shows the possible response codes for this operation:

Response CodeNameDescription
200OK

Request completed.

400Bad request

The system received an invalid value in a request.

401Unauthorized

The system received a request from a user that is not authenticated.

403Forbidden

The system received a request that the user is not authorized to make.

500Internal Server Error

An unexpected condition was encountered.

503Service Unavailable

The system is experiencing heavy load or another system failure.

 5.9.4.1. Request

This table shows the header parameters for the test an existing notification request:

NameTypeDescription

X-Auth-Token

​String

(Required)

A valid authentication token with administrative access.

This operation does not accept a request body.

 5.9.4.2. Response

 

Example 5.63. Test an existing notification: XML response

<?xml version="1.0" encoding="utf-8"?>
<notification_data>
  <status>success</status>
  <message>Success: Webhook successfully executed</message>
</notification_data>

 

Example 5.64. Test an existing notification: JSON response

{
    "status": "success",
    "message": "Success: Webhook successfully executed"
}

 5.9.5. Get notification by ID

 
MethodURIDescription
GET/notifications/{notificationId}

Returns information about the specified notification.

This table shows the possible response codes for this operation:

Response CodeNameDescription
200OK

The request completed.

401Unauthorized

The system received a request from a user that is not authenticated.

403Forbidden

The system received a request that the user is not authorized to make.

500Internal Server Error

An unexpected condition was encountered.

503Service Unavailable

The system is experiencing heavy load or another system failure.

 5.9.5.1. Request

This table shows the header parameters for the get notification by id request:

NameTypeDescription

X-Auth-Token

​String

(Required)

A valid authentication token with administrative access.

This operation does not accept a request body.

 5.9.5.2. Response

 

Example 5.65. Get notification by ID: XML response

<?xml version="1.0" encoding="utf-8"?>
<notification id="ntAAAA">
  <label>my webhook #1</label>
  <type>webhook</type>
  <details>
    <url>https://systems.example.org/alert</url>
  </details>
</notification>

 

Example 5.66. Get notification by ID: JSON response

{
    "id": "ntAAAA",
    "label": "my webhook #1",
    "type": "webhook",
    "details": {
        "url": "https://systems.example.org/alert"
    }
}

 5.9.6. Update a notification

 
MethodURIDescription
PUT/notifications/{notificationId}

Updates the specified notification with update attribute values submitted with the request.

This table shows the possible response codes for this operation:

Response CodeNameDescription
204No Content

The server has fulfilled the request but does not need to return an entity-body.

400Bad request

The system received an invalid value in a request.

401Unauthorized

The system received a request from a user that is not authenticated.

403Forbidden

The system received a request that the user is not authorized to make.

404Not Found

The URL or entity requested is not found in the system.

500Internal Server Error

An unexpected condition was encountered.

503Service Unavailable

The system is experiencing heavy load or another system failure.

 5.9.6.1. Request

This table shows the header parameters for the update a notification request:

NameTypeDescription

X-Auth-Token

​String

(Required)

A valid authentication token with administrative access.

 

Example 5.67. Update a notification: XML request

<?xml version="1.0" encoding="utf-8"?>
<notification>
  <type>webhook</type>
  <details>
    <url>https://systems.example.org/new_alert</url>
  </details>
</notification>

 

Example 5.68. Update a notification: JSON request

{
    "type": "webhook",
    "details": {
        "url": "https://systems.example.org/new_alert"
    }
}

 5.9.7. Delete a notification

 
MethodURIDescription
DELETE/notifications/{notificationId}

Deletes a notification from the user account.

This table shows the possible response codes for this operation:

Response CodeNameDescription
204No Content

The server has fulfilled the request but does not need to return an entity-body.

401Unauthorized

The system received a request from a user that is not authenticated.

403Forbidden

The system received a request that the user is not authorized to make.

404Not Found

The URL or entity requested is not found in the system.

500Internal Server Error

An unexpected condition was encountered.

503Service Unavailable

The system is experiencing heavy load or another system failure.

 5.9.7.1. Request

This table shows the header parameters for the delete a notification request:

NameTypeDescription

X-Auth-Token

​String

(Required)

A valid authentication token with administrative access.

This operation does not accept a request body.



loading table of contents...