Notification channels

Notification channel list

GET /api/v0/channels

Required permissions for API key

  • Read

Response

Success

{
  "channels": [<channel>, <channel>, ...]
}

<channel> is an object with the following keys

KEY TYPE DESCRIPTION
id string the notification channel ID
name string the name of the notification channel
type string the type of notification channel ("email", "slack", "line", "chatwork", "typetalk", "hipchat", "twilio", "reactio", "pagerduty", "opsgenie", "yammer", "webhook")

In addition to that above, the following detailed information returns if the type is "email", "slack", or "webhook",

When the type is email
KEY TYPE DESCRIPTION
emails array[string] email addresses specified to receive notifications
userIds array[string] user IDs specified to receive notifications
events array[string] notification events ("alert" or "alertGroup")
When the type is slack
KEY TYPE DESCRIPTION
url string Incoming Webhook URL for Slack
mentions hash[string] the key is the condition (ok, warning, or critical), the value is the text accompanying the alert notification
enabledGraphImage boolean whether posting related graphs to Slack or not
events array[string] notification events ("alert", "alertGroup", "hostStatus", "hostRegister", "hostRetire", or "monitor")
When the type is webhook
KEY TYPE DESCRIPTION
url string URL that will receive HTTP request
events array[string] notification events ("alert", "alertGroup", "hostStatus", "hostRegister", "hostRetire", or "monitor")

Register notification channels

※Currently supported for email, Slack, and Webhook.

POST /api/v0/channels

Required permissions for API key

  • Read
  • Write

email notifications

Input(email notifications)

KEY TYPE DESCRIPTION
type string fixed character string "email"
name string the name of the channel
emails array[string] email addresses specified to receive notifications
userIds array[string] user IDs specified to receive notifications
events array[string] notfication events ("alert" or "alertGroup")

Response(email notifications)

Success
{
  "id": <channelId>,
  "type": "email",
  "name": "My Channel",
  "emails": ["myaddress@example.com"],
  "userIds": ["userId"],
  "events": ["alert"]
}
Error
STATUS CODE DESCRIPTION
400 when the address in emails is invalid
400 when a user that does not belong to the organization is included in userIds
400 when events contains an event other than those listed above
403 when the API doesn't have the required permissions / when accessing from outside the permitted IP address range

Slack

Input(Slack)

The object contains the following keys

KEY TYPE DESCRIPTION
type string fixed character string "slack"
name string the name of the channel
url string Incoming Webhook URL for Slack
mentions hash[string] the key is the condition (ok, warning, or critical), the value is the text accompanying the alert notification
enabledGraphImage boolean whether posting related graphs to Slack or not
events array[string] notification events ("alert", "alertGroup", "hostStatus", "hostRegister", "hostRetire", or "monitor")

Response(Slack)

Success
{
  "id": <channelId>,
  "type": "slack",
  "name": "My Channel",
  "url": "https://hooks.slack.com/services/TAAAA/BBBB/XXXXX",
  "mentions": {
    "ok": "ok message",
    "warning": "warning message"
  },
  "enabledGraphImage": true,
  "events": ["alert"]
}
Error
STATUS CODE DESCRIPTION
400 when the url is invalid
400 when events contains an event other than those listed above
403 when the API doesn't have the required permissions / when accessing from outside the permitted IP address range

Webhook

Input(Webhook)

KEY TYPE DESCRIPTION
type string fixed character string "webhook"
name string the name of the channel
url string URL that will receive HTTP request
events array[string] notification events ("alert", "alertGroup", "hostStatus", "hostRegister", "hostRetire", or "monitor")

Response(Webhook)

Success
{
  "id": <channelId>,
  "type": "webhook",
  "name": "My Channel",
  "url": "http://example.com/webhook",
  "events": ["alert"]
}
Error
STATUS CODE DESCRIPTION
400 when the url is invalid
400 when events contains an event other than those listed above
403 when the API doesn't have the required permissions / when accessing from outside the permitted IP address range

Delete notification channels

Deleting the channel

DELETE /api/v0/channels/<channelId>

Required permissions for API key

  • Read
  • Write

Response

The status of the channel before deletion is returned

Success

The format is the same as the channel list API <channel>

Error

STATUS CODE DESCRIPTION
404 when the supported channel can not be found in <channelId>
403 when the API doesn't have the required permissions / when accessing from outside the permitted IP address range