5.10. Notifications

A notification is a destination to which an alert is sent. It can be a variety of different notification types, which 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.

Concept: Notification and notification type, in Monitoring key terms and concepts

Next step: Create a notification plan

Table 5.13. 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/test-notification

Test a notification.

GET/notifications​{?id}

Lists the notifications for the account. Use /notifications?id=notificationOneId& id=notificationTwoId to filter the results to only include information on the specified notifications.

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.10.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.10.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. For details, see Retrieving an authentication token

 

Example 5.30. Create webhook notification: JSON request

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

 

Example 5.31. Create email notification: JSON request

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

 

Example 5.32. Create PagerDuty notification: JSON request

{
  "label": "my PagerDuty #1",
  "type": "pagerduty",
  "details": {
  "service_key": "abcd1234abcd1234abcd1234abcd1234"
  }
}

 

Example 5.33. Create SMS notification: JSON request

{
  "label": "my SMS #1",
  "type": "sms",
  "details": {
  "phone_number": "+15551234567"
  }
}

 5.10.2. Test a notification

 
MethodURIDescription
POST/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.10.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. For details, see Retrieving an authentication token

 

Example 5.34. Test notification: JSON request

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

 5.10.2.2. Response

 

Example 5.35. Test notification: JSON response

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

 5.10.3. List notifications

 
MethodURIDescription
GET/notifications​{?id}

Lists the notifications for the account. Use /notifications?id=notificationOneId& id=notificationTwoId to filter the results to only include information on the specified notifications.

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.10.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. For details, see Retrieving an authentication token

This operation does not accept a request body.

 5.10.3.2. Response

 

Example 5.36. 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.10.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.10.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. For details, see Retrieving an authentication token

This operation does not accept a request body.

 5.10.4.2. Response

 

Example 5.37. Test existing notification: JSON response

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

 5.10.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.10.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. For details, see Retrieving an authentication token

This operation does not accept a request body.

 5.10.5.2. Response

 

Example 5.38. Get notification by ID: JSON response

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

 5.10.6. Update a notification

 
MethodURIDescription
PUT/notifications/{notificationId}

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

Update a 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
204No Content

The server has fulfilled the request. Does not return a response 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, entity, or account 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.10.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. For details, see Retrieving an authentication token

 

Example 5.39. Update notification: JSON request

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

 5.10.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. Does not return a response 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, entity, or account 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.10.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. For details, see Retrieving an authentication token

This operation does not accept a request body.



Contents Search
loading table of contents...