Notifications#

A notification is a destination to which an alert is sent. Each notification must be be a variety of different notification types, which will evolve over time.

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

The default ntTechnicalContactsEmail notification emails all of the technical contacts on file for an account. You can use the default notification to create a notification plan just like you can for other notifications. The notification alerts the technical contacts only on state changes as defined in the notification plan.

Attributes

Name

Description

Validation

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 following notifications API operations to create, view, and manage notifications.

Create a notification#

POST /notifications

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

The following table shows the possible response codes for this operation:

Response Code

Name

Description

201

Accepted

‘Location’ header contains a link to the newly created check.

400

Bad request

The system received an invalid value in a request.

401

Unauthorized

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

403

Forbidden

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

500

Internal Server Error

An unexpected condition was encountered.

503

Service Unavailable

The system is experiencing heavy load or another system failure.

Request#

The following table shows the header parameters for the request:

Name

Type

Description

X-Auth-Token

String (Required)

A valid authentication token with administrative access. For details, see Get your credentials

Example Create webhook notification: JSON request

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

Example Create email notification: JSON request

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

Example Create PagerDuty notification: JSON request

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

Example Create SMS notification: JSON request

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

Response#

This operation does not return a response body.

Test a notification#

POST /test-notification

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

The following table shows the possible response codes for this operation:

Response Code

Name

Description

200

OK

Request completed.

400

Bad request

The system received an invalid value in a request.

401

Unauthorized

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

403

Forbidden

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

500

Internal Server Error

An unexpected condition was encountered.

503

Service Unavailable

The system is experiencing heavy load or another system failure.

Request#

The following table shows the header parameters for the request:

Name

Type

Description

X-Auth-Token

String (Required)

A valid authentication token with administrative access. For details, see Get your credentials

Example Test notification: JSON request

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

Response#

Example Test notification: JSON response

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

List notifications#

GET /notifications

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

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

The following table shows the possible response codes for this operation:

Response Code

Name

Description

200

OK

The request completed.

401

Unauthorized

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

403

Forbidden

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

500

Internal Server Error

An unexpected condition was encountered.

503

Service Unavailable

The system is experiencing heavy load or another system failure.

Request#

The following table shows the header parameters for the request:

Name

Type

Description

X-Auth-Token

String (Required)

A valid authentication token with administrative access. For details, see Get your credentials

Note

This operation does not accept a request body.

Response#

Example 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
    }
}

Test an existing notification#

POST /notifications/{notificationId}/test

This operation enables 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.

The following table shows the possible response codes for this operation:

Response Code

Name

Description

200

OK

Request completed.

400

Bad request

The system received an invalid value in a request.

401

Unauthorized

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

403

Forbidden

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

500

Internal Server Error

An unexpected condition was encountered.

503

Service Unavailable

The system is experiencing heavy load or another system failure.

Request#

The following table shows the header parameters for the request:

Name

Type

Description

X-Auth-Token

String (Required)

A valid authentication token with administrative access. For details, see Get your credentials

Note

This operation does not accept a request body.

Response#

Example Test existing notification: JSON response

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

Get notification by ID#

GET /notifications/{notificationId}

Returns information about the specified notification.

The following table shows the possible response codes for this operation:

Response Code

Name

Description

200

OK

The request completed.

401

Unauthorized

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

403

Forbidden

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

500

Internal Server Error

An unexpected condition was encountered.

503

Service Unavailable

The system is experiencing heavy load or another system failure.

Request#

The following table shows the header parameters for the request:

Name

Type

Description

X-Auth-Token

String (Required)

A valid authentication token with administrative access. For details, see Get your credentials

Note

This operation does not accept a request body.

Response#

Example Get notification by ID: JSON response

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

Update a notification#

PUT /notifications/{notificationId}

Update a notification in the monitoring system by using a valid set of attributes from the notifications attributes table.

The following table shows the possible response codes for this operation:

Response Code

Name

Description

204

No Content

The server has fulfilled the request. Does not return a response body.

400

Bad request

The system received an invalid value in a request.

401

Unauthorized

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

403

Forbidden

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

404

Not Found

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

500

Internal Server Error

An unexpected condition was encountered.

503

Service Unavailable

The system is experiencing heavy load or another system failure.

Request#

The following table shows the header parameters for the request:

Name

Type

Description

X-Auth-Token

String (Required)

A valid authentication token with administrative access. For details, see Get your credentials

Example Update notification: JSON request

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

Response#

This operation does not return a response body.

Delete a notification#

DELETE /notifications/{notificationId}

Deletes a notification from the user account.

The following table shows the possible response codes for this operation:

Response Code

Name

Description

204

No Content

The server has fulfilled the request. Does not return a response body.

401

Unauthorized

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

403

Forbidden

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

404

Not Found

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

500

Internal Server Error

An unexpected condition was encountered.

503

Service Unavailable

The system is experiencing heavy load or another system failure.

Request#

The following table shows the header parameters for the request:

Name

Type

Description

X-Auth-Token

String (Required)

A valid authentication token with administrative access. For details, see Get your credentials

Note

This operation does not accept a request body.

Response#

This operation does not return a response body.