• /
  • Log in
  • Free account

NerdGraph tutorial: Notification channels

You can manage your alert notification channels using our GraphQL NerdGraph API. Here are some queries and mutations you can develop in our NerdGraph API explorer.

Tip

See the NerdGraph introduction for help getting started with NerdGraph API 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.

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.

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.

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.

For more help

If you need more help, check out these support and learning resources:

Create issueEdit page
Copyright © 2021 New Relic Inc.