Notification channels

List Notification Channels

GET /api/v0/channels

Required permissions for the 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", "twilio", "pagerduty", "opsgenie", "jira-service-management", "microsoft-teams, "webhook", "amazon-event-bridge")
suspendedAt number / null the notification channel suspended timestamp (in epoch seconds)
null when not suspended

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", "alertGroup", "hostStatus", "hostRegister", "hostRetire", or "monitor")
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 or not the corresponding graph is posted to Slack
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
enabledGraphImage boolean whether or not the URL of the corresponding graph is included in the notification content
events array[string] notification events ("alert", "alertGroup", "hostStatus", "hostRegister", "hostRetire", or "monitor")

Register Notification Channel

※Currently supported for email, Slack, and Webhook.

POST /api/v0/channels

Required permissions for the 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] notification events ("alert", "alertGroup", "hostStatus", "hostRegister", "hostRetire", or "monitor")

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 key 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 or not the corresponding graph is posted to Slack
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 key 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
enabledGraphImage boolean whether or not the URL of the corresponding graph is included in the notification content
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",
  "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 key doesn't have the required permissions / when accessing from outside the permitted IP address range

Update Notification Channel

Update a notification channel.

※Currently supported for email, Slack, and Webhook.

PUT /api/v0/channels/<channelId>

Required permissions for the API key

  • Read
  • Write

Input

The format for the update is the same as Register Notification Channel.

However, the type cannot be changed.

Response

Success

The updated notification channel is returned. The response format is the same as that which can be obtained with Register Notification Channel.

Error

STATUS CODE DESCRIPTION
400 when the JSON format is incorrect
400 when attempting to change the channel type
404 when the channel corresponding to <channelId> cannot be found
403 when the API key doesn't have write permissions / when accessing from outside the permitted IP address range

Delete Notification Channel

Delete the channel

DELETE /api/v0/channels/<channelId>

Required permissions for the 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 key doesn't have the required permissions / when accessing from outside the permitted IP address range