This document describes how to create and manage notification channels by using client libraries or by using the Google Cloud CLI, both of which invoke the Cloud Monitoring API. Cloud Monitoring uses notification channels to notify you, or your on-call team, when the condition of an alerting policy is met. There are several available channel types; each type is described in a notification-channel descriptor. A notification channel of a certain type is an instance of that type's descriptor. Your alerting policies include references to the notification channels to use as notification pathways.
A notification channel must exist before it can be used in an alerting policy. The notification-channel descriptors are provided to you, but you have to create the channels before they can be used.
To configure notification channels by using the Google Cloud console, see Create and manage notification channels.
The code samples used in this document are extracted from the alerting-policy API example, described in Example: backup and restore.
About the API
The NotificationChannel resource supports operations that let you manage your notification channels. It also supports operations related to managing the verificationStatus field of a channel:
- Sending a verification code
- Generating a code for copying the verification status of a verified channel to other identical channels in the same or a new project
- Verifying the channel using the code created by the previous two operations
For more information, see the notificationChannels reference documents.
Before you begin
-  To get the permissions that you need to view and configure notification channels by using the Cloud Monitoring API, ask your administrator to grant you the Monitoring NotificationChannel Editor ( roles/monitoring.notificationChannelEditor) IAM role on your project. For more information about granting roles, see Manage access to projects, folders, and organizations.You might also be able to get the required permissions through custom roles or other predefined roles. For more information about Cloud Monitoring roles, see Control access with Identity and Access Management. 
-  Select the tab for how you plan to use the samples on this page: gcloudIn the Google Cloud console, activate Cloud Shell. At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize. C#To use the .NET samples on this page in a local development environment, install and initialize the gcloud CLI, and then set up Application Default Credentials with your user credentials. Install the Google Cloud CLI. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity. If you're using a local shell, then create local authentication credentials for your user account: gcloud auth application-default login You don't need to do this if you're using Cloud Shell. If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity. For more information, see Set up ADC for a local development environment in the Google Cloud authentication documentation. GoTo use the Go samples on this page in a local development environment, install and initialize the gcloud CLI, and then set up Application Default Credentials with your user credentials. Install the Google Cloud CLI. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity. If you're using a local shell, then create local authentication credentials for your user account: gcloud auth application-default login You don't need to do this if you're using Cloud Shell. If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity. For more information, see Set up ADC for a local development environment in the Google Cloud authentication documentation. JavaTo use the Java samples on this page in a local development environment, install and initialize the gcloud CLI, and then set up Application Default Credentials with your user credentials. Install the Google Cloud CLI. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity. If you're using a local shell, then create local authentication credentials for your user account: gcloud auth application-default login You don't need to do this if you're using Cloud Shell. If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity. For more information, see Set up ADC for a local development environment in the Google Cloud authentication documentation. Node.jsTo use the Node.js samples on this page in a local development environment, install and initialize the gcloud CLI, and then set up Application Default Credentials with your user credentials. Install the Google Cloud CLI. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity. If you're using a local shell, then create local authentication credentials for your user account: gcloud auth application-default login You don't need to do this if you're using Cloud Shell. If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity. For more information, see Set up ADC for a local development environment in the Google Cloud authentication documentation. PHPTo use the PHP samples on this page in a local development environment, install and initialize the gcloud CLI, and then set up Application Default Credentials with your user credentials. Install the Google Cloud CLI. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity. If you're using a local shell, then create local authentication credentials for your user account: gcloud auth application-default login You don't need to do this if you're using Cloud Shell. If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity. For more information, see Set up ADC for a local development environment in the Google Cloud authentication documentation. PythonTo use the Python samples on this page in a local development environment, install and initialize the gcloud CLI, and then set up Application Default Credentials with your user credentials. Install the Google Cloud CLI. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity. If you're using a local shell, then create local authentication credentials for your user account: gcloud auth application-default login You don't need to do this if you're using Cloud Shell. If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity. For more information, see Set up ADC for a local development environment in the Google Cloud authentication documentation. 
- If you plan to use the Google Cloud CLI, then configure the default project: - gcloud config set project PROJECT_ID- Before you run the previous command, replace the following: - PROJECT_ID: The identifier of the project. For App Hub configurations, select the App Hub host project or management project.
 
List the types of notification channels
Monitoring provides a number of built-in notification-channel types. Each of these types is described in a NotificationChannelDescriptor. These descriptors have a type field, and the value of this field acts as an identifier for it when creating instances of that channel type. To retrieve a list of channel types that you can create with the Cloud Monitoring API or the Google Cloud CLI, enter the following command:
$ gcloud beta monitoring channel-descriptors list --format='value(type)' campfire email google_chat hipchat pagerduty pubsub slack sms webhook_basicauth webhook_tokenauth For more information about notification channels, see Create and manage notification channels.
If your preferred notification channel isn't supported, consider creating a pipeline that relies on sending your notifications to Pub/Sub. For a Python example that uses Flask, see Creating custom notifications with Cloud Monitoring and Cloud Run. For other examples, see the cloud-alerting-notification-forwarding Git repository.
To retrieve all the channel descriptors in a Google Cloud project, use the notificationChannelDescriptors.list method. The retrieved descriptors are read-only.
If you are looking for a specific descriptor and you know its name, you can use the notificationChannelDescriptors.get method to retrieve only that channel descriptor. The name of a channel descriptor has the format projects/[PROJECT_ID]/notificationChannelDescriptors/[CHANNEL_TYPE] [CHANNEL_TYPE] must be one of the types previously listed. For example:
projects/[PROJECT_ID]/notificationChannelDescriptors/email
gcloud
To list all the notification-channel descriptors in a Google Cloud project, use the gcloud beta monitoring channel-descriptors list command:
gcloud beta monitoring channel-descriptors list If successful, the list command provides a listing of all the channel descriptors in the specified project. For example, the email channel descriptor appears in the list like this:
--- description: A channel that sends notifications via email. displayName: Email labels: - description: An address to send email. key: email_address name: projects/[PROJECT_ID]/notificationChannelDescriptors/email type: email ---
All channel descriptors include these fields:
- name: The fully qualified resource name of the channel descriptor
- type: The part of the name that indicates the type of channel
- displayName: A description of the- typefield, for display purposes
- description: A brief description of the channel
- labels: A set of fields specific to a channel type. Each channel type has its own set of labels.
When a channel is created, it also gets an enabled field, with the value true by default.
To list a single channel descriptor, use gcloud beta monitoring channel-descriptors describe, instead, and specify the name of the channel descriptor. You don't need to specify the fully qualified name. For example, both of these commands return the listing above:
gcloud beta monitoring channel-descriptors describe email gcloud beta monitoring channel-descriptors describe projects/[PROJECT_ID]/notificationChannelDescriptors/email See the gcloud beta monitoring channel-descriptors list and describe references for more information. The describe command corresponds to the notificationChannelDescriptors.get method in the API.
Create a notification channel
You can create notification channels for your Google Cloud projects from JSON or YAML files by using the Google Cloud CLI, and you can create them programmatically.
To create a notification channel, you must supply values for the fields in its descriptor. Most of these, like type, are common across all notification-channel descriptors; see notificationChannelDescriptors.
Each descriptor also has a set of labels, and this set varies across the descriptors. To see the set of labels for a particular descriptor, retrieve the descriptor using the gcloud beta monitoring channel-descriptors describe command described in List the types of notification channels. For example, retrieving the email channel descriptor shows a single label:
labels: - description: An address to send email. key: email_address
The pubsub channel descriptor also contains a single label; that label identifies the Pub/Sub topic. However, channels can contain multiple labels. For example, the slack channel descriptor has two labels:
labels: - description: A permanent authentication token provided by Slack. This field is obfuscated by returning only a few characters of the key when fetched. key: auth_token - description: The Slack channel to which to post notifications. key: channel_name
Retrieving the webhook_basicauth channel descriptor shows several labels:
labels: - description: The password. The field is obfuscated when the channel is fetched. key: password - description: The public URL to which to publish the webhook. key: url - description: The username. key: username
Whether you create a new channel programmatically or from the command line, the value of the type in your specification must match the type field in the corresponding notification-channel descriptor. Any required label keys must also match those in the channel descriptor.
Some labels correspond to credentials used to authenticate with the provider. When creating a channel, the values for these labels must be obtained from the provider. Obtaining a credential might involve using an API key-generation page on the provider's website or completing an OAuth login flow with the provider. The specifics of how to obtain such a credential depend on the particular provider.
For example, the following shows the specification of a new pubsub notification channel in JSON:
 { "type": "pubsub", "displayName": "Notifications", "description": "Pub/Sub channel for notifications", "labels": { "topic": "projects/[PROJECT_ID]/topics/notificationTopic" }, } The type value (pubsub) and the single label key (topic) match the type and labels.key fields in the corresponding channel descriptor.
Channels are enabled by default. If you want to create an inactive channel, you can include the field enabled with the value false.
The following examples illustrate the creation of notification channels.
gcloud
To create a notification channel in a Google Cloud project, use the gcloud beta monitoring channels create command. To load the channel from a file, use the --channel-content-from-file flag to specify the file.
The following example creates a new Pub/Sub channel from the pubsub-channel.json file:
gcloud beta monitoring channels create --channel-content-from-file="pubsub-channel.json" If successful, this command returns the name of the new channel, for example:
Created notification channel [projects/[PROJECT_ID]/notificationChannels/1355376463305411567].
See the gcloud beta monitoring channels create reference for more information.
C#
To authenticate to Monitoring, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Node.js
To authenticate to Monitoring, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Go
To authenticate to Monitoring, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Java
To authenticate to Monitoring, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
PHP
To authenticate to Monitoring, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Python
To authenticate to Monitoring, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Example: Create a Slack notification channel
To configure a notification channel for a Slack app, do the following:
- Configure your Slack app: - If you don't already have a Slack app, follow the Slack reference documentation to create one and install it to your workspace.
- Configure your Slack app with OAuth scopes for chat:writeandchat:write.public.
- Copy the app's Bot User OAuth token.
 
- Create a file that defines the configuration of your notification channel. Include a label where the - auth_tokenkey has the value of your Slack app's Bot User OAuth token. For example:- { "description": "A Slack notification channel", "displayName": "Slack", "type": "slack", "enabled": true, "labels": { "auth_token": "OAUTH_TOKEN_VALUE", "channel_name": "SLACK_CHANNEL_NAME" } }
- Run the following command to create the notification channel: - gcloud beta monitoring channels create --channel-content-from-file="FILE_NAME" 
List notification channels in a project
To retrieve all the notification channels in a Google Cloud project, use the notificationChannels.list method. This method also supports filter and orderBy options to restrict and sort the results; see Sorting and Filtering.
If you are looking for a specific channel and you know its name, you can use the notificationChannels.get method to retrieve only that channel. The name of a channel has the format projects/[PROJECT_ID]/notificationChannels/[CHANNEL_ID], for example:
projects/[PROJECT_ID]/notificationChannels/1355376463305411567
When you retrieve a channel, sensitive values like authentication tokens and API keys might be obfuscated for security reasons. If you are creating a new channel by copying an existing one, any obfuscated values need to be corrected.
gcloud
To list all the notification channels in a Google Cloud project, use the gcloud beta monitoring channels list command:
gcloud beta monitoring channels list If successful, the list command provides a listing of all the channels in the specified project. For example, the command above might return a list that includes the following entries:
--- description: E-mail channel created by gcloud as a test displayName: test e-mail channel enabled: false labels: email_address: user@example.com name: projects/[PROJECT_ID]/notificationChannels/1355376463305411567 type: email --- description: Pub/Sub channel for notifications displayName: Notifications enabled: true labels: topic: projects/[PROJECT_ID]/topics/notificationTopic name: projects/[PROJECT_ID]/notificationChannels/1355376463305411567 type: pubsub
To list a single channel, use gcloud beta monitoring channels describe, instead, and specify the name of the channel. For example, this command returns the Pub/Sub channel shown in the listing above:
gcloud beta monitoring channels describe projects/[PROJECT_ID]/notificationChannels/1355376463305411567 See the gcloud beta monitoring channels list and describe references for more information. The describe command corresponds to the notificationChannels.get method in the API.
C#
To authenticate to Monitoring, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Node.js
To authenticate to Monitoring, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Go
To authenticate to Monitoring, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Java
To authenticate to Monitoring, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
PHP
To authenticate to Monitoring, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Python
To authenticate to Monitoring, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Delete a notification channel from a project
To delete a notification channel from a Google Cloud project, use the notificationChannels.delete method, and supply the name of the notification channel to delete. The name of a channel is the value of the name field, not the displayName, in the NotificationChannel instance. The name of a channel has the format projects/[PROJECT_ID]/notificationChannels/[CHANNEL_ID], for example:
projects/[PROJECT_ID]/notificationChannels/1355376463305411567
By default, if you attempt to delete a channel that is referenced by an alerting policy, then the channel won't be deleted. To force the removal of references from alerting policies and delete the channel, set the force option to true. This option automatically removes the channel from all referencing policies.
gcloud
To delete a notification channel, use gcloud beta monitoring channels delete, and specify the name of the channel to delete. For example, the following command deletes the email channel created in another example:
gcloud beta monitoring channels delete projects/[PROJECT_ID]/notificationChannels/1355376463305411567 See the gcloud beta monitoring channels delete reference for more information. 
C#
To authenticate to Monitoring, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Go
To authenticate to Monitoring, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Java
To authenticate to Monitoring, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
PHP
To authenticate to Monitoring, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Node.js
To authenticate to Monitoring, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Python
To authenticate to Monitoring, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Modify a notification channel
To modify a notification channel, use the notificationChannels.patch method (in the REST API). Other API implementations and the Google Cloud CLI call this update instead of patch.
An update operation can wholly replace the existing channel, or it can modify a subset of fields. For example, you can enable and disable the channel. Disabling a channel prevents delivery of notifications to the channel. Disabling a channel is typically more convenient than removing the channel from the alerting policies that refer to it, if the change is intended to be temporary.
gcloud
To enable a notification channel that is disabled, use the gcloud beta monitoring channels update command, and provide the --enabled flag. The following command enables the email notification channel created—in the disabled state—in a previous example:
gcloud beta monitoring channels update projects/[PROJECT_ID]/notificationChannels/1355376463305411567 --enabled To disable a policy, use the same command and provide the --no-enabled flag. See the gcloud beta monitoring channels update reference for more information. The update command corresponds to the notificationChannels.patch method in the REST API.
C#
To authenticate to Monitoring, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Go
To authenticate to Monitoring, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Node.js
To authenticate to Monitoring, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Java
To authenticate to Monitoring, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
PHP
To authenticate to Monitoring, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Python
To authenticate to Monitoring, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
View notification channel logs
You can use the Logs Explorer to view notification channel errors:
-  In the Google Cloud console, go to the Logs Explorer page: If you use the search bar to find this page, then select the result whose subheading is Logging. 
- Enter and run your query. For queries specific to notification channel errors, see Cloud Monitoring queries.