NerdGraph tutorial: Notification channels

You can manage your alert notification channels using our NerdGraph API.

Tip

See the NerdGraph introduction for help getting started with NerdGraph and the NerdGraph explorer.

Get notification channels

The notificationChannels query allows you to paginate through all of your notification channels per account. You can also use the notificationChannel query to get a specific notification channel by its ID.

Tip

Note that certain secret fields (for example, passwords or API keys) are obfuscated in the returned fields.

This example returns every field for every notification channel on the supplied account ID, up to the page limit of 200. Note how we use inline fragments to refer to the specific fields on the concrete types implementing the AlertsNotificationChannel interface.

{
  actor {
    account(id: YOUR_ACCOUNT_ID) {
      alerts {
        notificationChannels {
          channels {
            id
            name
            type
            ... on AlertsXMattersNotificationChannel {
              config {
                integrationUrl
              }
            }
            ... on AlertsWebhookNotificationChannel {
              config {
                baseUrl
                basicAuth {
                  password
                  username
                }
                customHttpHeaders {
                  name
                  value
                }
                customPayloadBody
                customPayloadType
              }
            }
            ... on AlertsVictorOpsNotificationChannel {
              config {
                key
                routeKey
              }
            }
            ... on AlertsUserNotificationChannel {
              config {
                userId
              }
            }
            ... on AlertsSlackNotificationChannel {
              config {
                teamChannel
                url
              }
            }
            ... on AlertsPagerDutyNotificationChannel {
              config {
                apiKey
              }
            }
            ... on AlertsOpsGenieNotificationChannel {
              config {
                apiKey
                dataCenterRegion
                recipients
                tags
                teams
              }
            }
            ... on AlertsHipChatNotificationChannel {
              config {
                authToken
                baseUrl
                roomId
              }
            }
            ... on AlertsEmailNotificationChannel {
              config {
                emails
                includeJson
              }
            }
            ... on AlertsCampfireNotificationChannel {
              config {
                room
                subdomain
                token
              }
            }
          }
          totalCount
          nextCursor
        }
      }
    }
  }
}

If a given account's list of notification channels exceeds the 200 channel page limit, you can use the pagination cursor to retrieve additional pages.

With cursor pagination, you continue to request additional pages using the nextCursor until that field returns empty in the response. An empty nextCursor signals that you have reached the end of the result set.

Here's an example:

{
  actor {
    account(id: YOUR_ACCOUNT_ID) {
      alerts {
        notificationChannels {
          channels {
            id
            name
            type
          }
          totalCount
          nextCursor
        }
      }
    }
  }
}

The code above returns a set of results like this:

{
  "data": {
    "actor": {
      "account": {
        "alerts": {
          "notificationChannels": {
            "channels": [
              {
                "id": "250",
                "name": "Channel 1",
                "type": "SLACK"
              },
              {
                "id": "713",
                "name": "Channel 2",
                "type": "WEBHOOK"
              },
              // ... +198 more notification channels in reality
            ],
            "nextCursor": "Wh4LK9JYzfACVlNkyvf7Rg==:I5VbSEpgx3UWNA5AOVsUPv4=",
            "totalCount": 268
          }
        }
      }
    }
  }
}

In your next request, provide the cursor like so, updating each subsequent request to return the updated cursor, until the cursor is empty:

{
  actor {
    account(id: YOUR_ACCOUNT_ID) {
      alerts {
        notificationChannels(cursor: "Wh4LK9JYzfACVlNkyvf7Rg==:I5VbSEpgx3UWNA5AOVsUPv4=") {
          channels {
            id
            name
            type
          }
          totalCount
          nextCursor
        }
      }
    }
  }
}

If you have a specific notification channel's ID, the API allows you to look it up directly. Note that because the specific channel is a concrete type implementing the AlertsNotificationChannel interface, you may need to specify certain fields using the ... on syntax for inline fragments.

In this example, we are retrieving a Slack channel:

{
  actor {
    account(id: YOUR_ACCOUNT_ID) {
      alerts {
        notificationChannel(id: YOUR_CHANNEL_ID) {
          id
          name
          type
          ... on AlertsSlackNotificationChannel {
            config {
              teamChannel
              url
            }
          }
        }
      }
    }
  }
}

This example returns the ID, name, and type for every notification channel on the supplied account ID, as well as a list of every policy that is associated with that channel.

{
  actor {
    account(id: YOUR_ACCOUNT_ID) {
      alerts {
        notificationChannels {
          channels {
            id
            name
            type
            associatedPolicies {
              policies {
                id
                name
              }
              totalCount
            }
          }
          nextCursor
          totalCount
        }
      }
    }
  }
}

Create a notification channel

In order to create an alert notification channel, you need to know the specific type of notification channel you want to create (for example email, Slack, etc.), as well as the details necessary to configure it (which will depend on the channel type). Once a notification channel has been created, it can be associated with one or more alert policies. Once associated, those channels will receive notifications from those policies when conditions are violated.

Caution

While you can query for any existing notification channel type, you can only create a subset of them. Specifically, the user channel type has no editable fields, and the Campfire and HipChat channel types are both deprecated.

An example create mutation for an email notification channel:

mutation {
  alertsNotificationChannelCreate(accountId: YOUR_ACCOUNT_ID, notificationChannel: {
    email: {
      emails: ["email@example.com"],
      includeJson: true,
      name: "Some Name <email@example.com>"
    }
  }) {
    notificationChannel {
      ... on AlertsEmailNotificationChannel {
        id
        name
        type
        config {
          emails
          includeJson
        }
      }
    }
    error {
      description
      errorType
    }
  }
}

An example create mutation for an OpsGenie notification channel:

mutation {
  alertsNotificationChannelCreate(accountId: YOUR_ACCOUNT_ID, notificationChannel: {
    opsGenie: {
      apiKey: "api-key-from-opsgenie",
      dataCenterRegion: US,
      name: "OpsGenie notification channel name",
      recipients: ["user@example.com"],
      tags: ["tag1", "tag2"],
      teams: ["team1", "team2"]
    }
  }) {
    notificationChannel {
      ... on AlertsOpsGenieNotificationChannel {
        id
        name
        type
        config {
          apiKey
          teams
          tags
          recipients
          dataCenterRegion
        }
      }
    }
    error {
      description
      errorType
    }
  }
}

An example create mutation for a PagerDuty notification channel:

mutation {
  alertsNotificationChannelCreate(accountId: YOUR_ACCOUNT_ID, notificationChannel: {
    pagerDuty: {
      name: "PagerDuty notification channel name",
      apiKey: "api-key-from-pagerduty"
    }
  }) {
    notificationChannel {
      ... on AlertsPagerDutyNotificationChannel {
        id
        name
        type
        config {
          apiKey
        }
      }
    }
    error {
      description
      errorType
    }
  }
}

An example create mutation for a Slack notification channel:

mutation {
  alertsNotificationChannelCreate(accountId: YOUR_ACCOUNT_ID, notificationChannel: {
    slack: {
      name: "Slack notification channel name",
      teamChannel: "#team-channel",
      url: "https://hooks.slack.com/services/FAKE/MOREFAKE/IMAGINARYEXAMPLEURLCHUNK"
    }
  }) {
    notificationChannel {
      ... on AlertsSlackNotificationChannel {
        id
        name
        type
        config {
          teamChannel
          url
        }
      }
    }
    error {
      description
      errorType
    }
  }
}

An example create mutation for a VictorOps notification channel:

mutation {
  alertsNotificationChannelCreate(accountId: YOUR_ACCOUNT_ID, notificationChannel: {
    victorOps: {
      key: "example-api-key-from-victorops",
      name: "VictorOps notification channel name",
      routeKey: "example-route-key"
    }
  }) {
    notificationChannel {
      ... on AlertsVictorOpsNotificationChannel {
        id
        name
        type
        config {
          key
          routeKey
        }
      }
    }
    error {
      description
      errorType
    }
  }
}

An example create mutation for a Webhook notification channel:

mutation {
  alertsNotificationChannelCreate(accountId: YOUR_ACCOUNT_ID, notificationChannel: {
    webhook: {
      baseUrl: "https://example.com/webhook",
      basicAuth: {
        password: "t0t4lly-s3cr3t-p455w0rd",
        username: "webhook-user"
      },
      customHttpHeaders: [
        {name: "X-Api-Key", value: "100%-real-api-key"},
        {name: "X-Calling-Service", value: "New Relic Alerts"}
      ],
      customPayloadBody: "{ \"account_id\": \"$ACCOUNT_ID\", \"account_name\": \"$ACCOUNT_NAME\", \"closed_violations_count_critical\": \"$CLOSED_VIOLATIONS_COUNT_CRITICAL\", \"closed_violations_count_warning\": \"$CLOSED_VIOLATIONS_COUNT_WARNING\", \"condition_description\": \"$DESCRIPTION\", \"condition_family_id\": \"$CONDITION_FAMILY_ID\", \"condition_name\": \"$CONDITION_NAME\", \"current_state\": \"$EVENT_STATE\", \"details\": \"$EVENT_DETAILS\", \"duration\": \"$DURATION\", \"event_type\": \"$EVENT_TYPE\", \"incident_acknowledge_url\": \"$INCIDENT_ACKNOWLEDGE_URL\", \"incident_id\": \"$INCIDENT_ID\", \"incident_url\": \"$INCIDENT_URL\", \"metadata\": \"$METADATA\", \"open_violations_count_critical\": \"$OPEN_VIOLATIONS_COUNT_CRITICAL\", \"open_violations_count_warning\": \"$OPEN_VIOLATIONS_COUNT_WARNING\", \"owner\": \"$EVENT_OWNER\", \"policy_name\": \"$POLICY_NAME\", \"policy_url\": \"$POLICY_URL\", \"runbook_url\": \"$RUNBOOK_URL\", \"severity\": \"$SEVERITY\", \"targets\": \"$TARGETS\", \"timestamp\": \"$TIMESTAMP\", \"timestamp_utc_string\": \"$TIMESTAMP_UTC_STRING\", \"violation_callback_url\": \"$VIOLATION_CALLBACK_URL\", \"violation_chart_url\": \"$VIOLATION_CHART_URL\" }",
      customPayloadType: JSON,
      name: "Webhook notification channel name"
    }
  }) {
    notificationChannel {
      ... on AlertsWebhookNotificationChannel {
        id
        name
        type
        config {
          customPayloadType
          customPayloadBody
          customHttpHeaders {
            value
            name
          }
          basicAuth {
            password
            username
          }
          baseUrl
        }
      }
    }
    error {
      description
      errorType
    }
  }
}

An example create mutation for an xMatters notification channel:

mutation {
  alertsNotificationChannelCreate(accountId: YOUR_ACCOUNT_ID, notificationChannel: {
    xMatters: {
      integrationUrl: "https://company.instance.xmatters.com/api/xm/v<version>/...",
      name: "xMatters notification channel name"
    }
  }) {
    notificationChannel {
      ... on AlertsXMattersNotificationChannel {
        id
        name
        type
        config {
          integrationUrl
        }
      }
    }
    error {
      description
      errorType
    }
  }
}

Update a notification channel

In order to update an alert notification channel, you need to know the specific type of notification channel you want to change (for example email, Slack, etc.), as well as the details necessary to configure it (which will depend on the channel type). Consistent with other GraphQL APIs, you can update a single field on the channel without knowing anything other than the channel's ID.

Caution

While you can query for any existing notification channel type, you can only update a subset of them. Specifically, the user channel type has no editable fields, and the Campfire and HipChat channel types are both deprecated.

An example update mutation for an email notification channel where we're updating only the name:

mutation {
  alertsNotificationChannelUpdate(accountId: YOUR_ACCOUNT_ID, id: YOUR_CHANNEL_ID, notificationChannel: {
    email: {
      name: "Updated Name <email@example.com>"
    }
  }) {
    notificationChannel {
      ... on AlertsEmailNotificationChannel {
        id
        name
        type
      }
    }
    error {
      description
      errorType
      notificationChannelId
    }
  }
}

An example update mutation for an OpsGenie notification channel where we're updating only the name:

mutation {
  alertsNotificationChannelUpdate(accountId: YOUR_ACCOUNT_ID, id: YOUR_CHANNEL_ID, notificationChannel: {
    opsGenie: {
      name: "OpsGenie updated channel name"
    }
  }) {
    notificationChannel {
      ... on AlertsOpsGenieNotificationChannel {
        id
        name
        type
      }
    }
    error {
      description
      errorType
      notificationChannelId
    }
  }
}

An example update mutation for a PagerDuty notification channel where we're updating only the name:

mutation {
  alertsNotificationChannelUpdate(accountId: YOUR_ACCOUNT_ID, id: YOUR_CHANNEL_ID, notificationChannel: {
    pagerDuty: {
      name: "PagerDuty updated channel name"
    }
  }) {
    notificationChannel {
      ... on AlertsPagerDutyNotificationChannel {
        id
        name
        type
      }
    }
    error {
      description
      errorType
      notificationChannelId
    }
  }
}

An example update mutation for a Slack notification channel where we're updating only the name:

mutation {
  alertsNotificationChannelUpdate(accountId: YOUR_ACCOUNT_ID, id: YOUR_CHANNEL_ID, notificationChannel: {
    slack: {
      name: "Slack updated channel name"
    }
  }) {
    notificationChannel {
      ... on AlertsSlackNotificationChannel {
        id
        name
        type
      }
    }
    error {
      description
      errorType
      notificationChannelId
    }
  }
}

An example update mutation for a VictorOps notification channel where we're updating only the name:

mutation {
  alertsNotificationChannelUpdate(accountId: YOUR_ACCOUNT_ID, id: YOUR_CHANNEL_ID, id: YOUR_CHANNEL_ID, notificationChannel: {
    victorOps: {
      name: "VictorOps updated channel name"
    }
  }) {
    notificationChannel {
      ... on AlertsVictorOpsNotificationChannel {
        id
        name
        type
      }
    }
    error {
      description
      errorType
      notificationChannelId
    }
  }
}

An example update mutation for a Webhook notification channel where we're updating only the name:

mutation {
  alertsNotificationChannelUpdate(accountId: YOUR_ACCOUNT_ID, id: YOUR_CHANNEL_ID, notificationChannel: {
    webhook: {
      name: "Webhook updated channel name"
    }
  }) {
    notificationChannel {
      ... on AlertsWebhookNotificationChannel {
        id
        name
        type
      }
    }
    error {
      description
      errorType
      notificationChannelId
    }
  }
}

An example update mutation for an xMatters notification channel where we're updating only the name:

mutation {
  alertsNotificationChannelUpdate(accountId: YOUR_ACCOUNT_ID, id: YOUR_CHANNEL_ID, notificationChannel: {
    xMatters: {
      name: "xMatters updated channel name"
    }
  }) {
    notificationChannel {
      ... on AlertsXMattersNotificationChannel {
        id
        name
        type
      }
    }
    error {
      description
      errorType
      notificationChannelId
    }
  }
}

Delete a notification channel

You can delete a notification channel with only the account ID and the channel ID. Note that deleting a channel dissociates it from all policies, meaning that no further notifications will be sent to that channel.

mutation {
  alertsNotificationChannelDelete(accountId: YOUR_ACCOUNT_ID,
  id: YOUR_CHANNEL_ID) {
    id
    error {
      description
      errorType
      notificationChannelId
    }
  }
}

Associate channels to a policy

Creating an alert notification channel is not enough: Once the channel has been created, it needs to be associated to one or more policies. Once associated to a policy, the channel can recieve alert notifications when conditions on that policy go into violation.

In this example, we associate two channels with a policy:

mutation {
  alertsNotificationChannelsAddToPolicy(accountId: YOUR_ACCOUNT_ID,
    notificationChannelIds: [FIRST_CHANNEL_ID, SECOND_CHANNEL_ID],
    policyId: YOUR_POLICY_ID
  ) {
    notificationChannels {
      id
    }
    policyId
    errors {
      description
      errorType
      notificationChannelId
    }
  }
}

Dissociate a channel from a policy

In those instances where a notification channel has outlived its usefulness (for example, an email list that has been retired), the time has come to dissociate that channel from the policy (or policies) that are sending alert notifications to it. This API call leaves the channel itself intact, but removes it from the specified policy.

In this example, we are removing two channels from a policy (leaving any others in place), and getting back confirmation that those two channel IDs have been removed:

mutation {
  alertsNotificationChannelsRemoveFromPolicy(accountId: YOUR_ACCOUNT_ID,
    notificationChannelIds: [FIRST_CHANNEL_ID, SECOND_CHANNEL_ID],
    policyId: YOUR_POLICY_ID
  ) {
    notificationChannels {
      id
    }
    policyId
    errors {
      description
      errorType
      notificationChannelId
    }
  }
}

Tip

Removing an alert notification channel from a policy does not delete the channel because it might be used by other policies. On the other hand, deleting a channel will cause all associated policies to stop sending alert notifications to that channel.

NerdGraph tutorial: Notification channels

Tip

Get notification channels

Tip

List all notification channels for an account

Paginate through notification channels with cursor pagination

Find a specific notification channel by id

List notification channels with their associated policies

Create a notification channel

Caution

Create an email notification channel

Create an OpsGenie notification channel

Create a PagerDuty notification channel

Create a Slack notification channel

Create a VictorOps notification channel

Create a Webhook notification channel

Create an xMatters notification channel

Update a notification channel

Caution

Update an email notification channel

Update an OpsGenie notification channel

Update a PagerDuty notification channel

Update a Slack notification channel

Update a VictorOps notification channel

Update a Webhook notification channel

Update an xMatters notification channel

Delete a notification channel

Associate channels to a policy

Dissociate a channel from a policy

Tip