Configure Pub/Sub notifications for Cloud Storage

Overview

This page describes how to configure your bucket to send notifications about object changes to a Pub/Sub topic. For information on subscribing to a Pub/Sub topic that receives notifications, see Choose a subscription type.

Before you begin

Before using this feature, complete the following instructions.

Enable the Pub/Sub API

Enable the Pub/Sub API for the project that will receive notifications.

Enable the API

Get required roles

To get the permissions that you need to configure and view Pub/Sub notifications for a bucket, ask your administrator to grant you the following roles. These predefined roles contain the permissions required to configure and view Pub/Sub notifications.

  • Storage Admin (roles/storage.admin) role on the bucket for which you want to configure Pub/Sub notifications

  • Pub/Sub Admin (roles/pubsub.admin) role on the project in which you want to receive Pub/Sub notifications

You might be able to get these permissions with other predefined roles or custom roles.

See Set and manage IAM policies on buckets for instructions on granting roles on buckets. See Controlling access for instructions on granting roles on projects and setting access controls for topics and subscriptions.

Make sure you have an existing Pub/Sub topic

If you haven't already, create a Pub/Sub topic to which you want to send notifications. This step is not necessary if you plan on using the Google Cloud CLI or Terraform to perform the instructions on this page.

Grant required role to your project's service agent

The following steps are not necessary if you plan on using the Google Cloud CLI or Terraform to perform the instructions on this page.

  1. Get the email address of the service agent associated with the project that contains your Cloud Storage bucket.

  2. Grant the service agent the Pub/Sub Publisher (roles/pubsub.publisher) role for the relevant Pub/Sub topic. See Controlling access for instructions on granting roles for topics.

Apply a notification configuration

The following steps add a notification configuration to your bucket that sends notifications for all supported events.

Console

You cannot manage Pub/Sub notifications with the Google Cloud console. Use the gcloud CLI or one of the available client libraries instead.

Command line

Use the gcloud storage buckets notifications create command:

gcloud storage buckets notifications create gs://BUCKET_NAME --topic=TOPIC_NAME

Where:

  • BUCKET_NAME is the name of the relevant bucket. For example, my-bucket.

  • TOPIC_NAME is the Pub/Sub topic to send notifications to. If you specify a topic that doesn't exist in your project, the command creates one for you.

To send notifications for a subset of events, include the --event-types flag.

Client libraries

C++

For more information, see the Cloud Storage C++ API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set up authentication for client libraries.

C#

For more information, see the Cloud Storage C# API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set up authentication for client libraries.

Go

For more information, see the Cloud Storage Go API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set up authentication for client libraries.

Java

For more information, see the Cloud Storage Java API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set up authentication for client libraries.

Node.js

For more information, see the Cloud Storage Node.js API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set up authentication for client libraries.

PHP

For more information, see the Cloud Storage PHP API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set up authentication for client libraries.

To create a notification configuration for a bucket using PHP, see the Google Cloud Client Library reference documentation.

Python

For more information, see the Cloud Storage Python API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set up authentication for client libraries.

Ruby

For more information, see the Cloud Storage Ruby API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set up authentication for client libraries.

Terraform

You can use a Terraform resource to add a notification configuration to a bucket.

REST APIs

JSON API

  1. Have gcloud CLI installed and initialized, which lets you generate an access token for the Authorization header.

  2. Create a JSON file that contains the following information:

    {
  "topic": "projects/PROJECT_ID/topics/TOPIC_NAME",
  "payload_format": "JSON_API_V1"
}

    Where:

    • PROJECT_ID is the ID for the project associated with the Pub/Sub topic that you want to send notifications to. For example, my-pet-project.

    • TOPIC_NAME is the Pub/Sub topic to send notifications to. For example, my-topic.

    To send notifications for a subset of events, include the event_types field in the body of your JSON request.

  3. Use cURL to call the JSON API with a POST notificationConfigs request:

    curl -X POST --data-binary @JSON_FILE_NAME \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/notificationConfigs"

    Where:

    • JSON_FILE_NAME is the path for the file that you created in Step 2.

    • BUCKET_NAME is the name of the bucket you want notifications to be generated for. For example, my-bucket.

XML API

You cannot manage Pub/Sub notifications with the XML API.

Get a notification configuration

To get a specific notification configuration that's associated with your bucket, complete the following steps:

Console

You cannot manage Pub/Sub notifications with the Google Cloud console. Use the Google Cloud CLI or one of the available client libraries instead.

Command line

Use the gcloud storage buckets notifications describe command:

gcloud storage buckets notifications describe projects/_/buckets/BUCKET_NAME/notificationConfigs/NOTIFICATION_ID

Where:

  • BUCKET_NAME is the name of the bucket whose notification configuration you want to retrieve For example, my-bucket.

  • NOTIFICATION_ID is the ID number of the relevant configuration. For example, 5.

If successful, the response looks similar to the following example:

etag: '132'
id: '132'
kind: storage#notification
payload_format: JSON_API_V1
selfLink: https://www.googleapis.com/storage/v1/b/my-bucket/notificationConfigs/132
topic: //pubsub.googleapis.com/projects/my-project/topics/my-bucket

Client libraries

C++

For more information, see the Cloud Storage C++ API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set up authentication for client libraries.

C#

For more information, see the Cloud Storage C# API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set up authentication for client libraries.

Go

For more information, see the Cloud Storage Go API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set up authentication for client libraries.

Java

For more information, see the Cloud Storage Java API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set up authentication for client libraries.

Node.js

For more information, see the Cloud Storage Node.js API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set up authentication for client libraries.

PHP

For more information, see the Cloud Storage PHP API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set up authentication for client libraries.

To get a notification configuration for a bucket using PHP, see the Google Cloud Client Library reference documentation.

Python

For more information, see the Cloud Storage Python API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set up authentication for client libraries.

Ruby

For more information, see the Cloud Storage Ruby API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set up authentication for client libraries.

REST APIs

JSON API

  1. Have gcloud CLI installed and initialized, which lets you generate an access token for the Authorization header.

  2. Use cURL to call the JSON API with a GET notificationConfigs request:

    curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/notificationConfigs/NOTIFICATION_ID"

    Where:

    • BUCKET_NAME is the name of the bucket whose notification configuration you want to retrieve. For example, my-bucket.

    • NOTIFICATION_ID is the ID number of the notification configuration you want to retrieve. For example, 5.

XML API

You cannot manage Pub/Sub Notifications with the XML API.

List notification configurations for a bucket

To list all the notification configurations associated with a particular bucket:

Console

You cannot manage Pub/Sub notifications with the Google Cloud console. Use the gcloud CLI or one of the available client libraries instead.

Command line

Use the gcloud storage buckets notifications list command:

gcloud storage buckets notifications list gs://BUCKET_NAME

Where BUCKET_NAME is the name of the bucket whose notification configurations you want to list. For example, my-bucket.

Client libraries

C++

For more information, see the Cloud Storage C++ API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set up authentication for client libraries.

C#

For more information, see the Cloud Storage C# API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set up authentication for client libraries.

Go

For more information, see the Cloud Storage Go API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set up authentication for client libraries.

Java

For more information, see the Cloud Storage Java API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set up authentication for client libraries.

Node.js

For more information, see the Cloud Storage Node.js API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set up authentication for client libraries.

PHP

For more information, see the Cloud Storage PHP API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set up authentication for client libraries.

To list notification configurations associated with a bucket using PHP, see the Google Cloud Client Library reference documentation.

Python

For more information, see the Cloud Storage Python API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set up authentication for client libraries.

Ruby

For more information, see the Cloud Storage Ruby API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set up authentication for client libraries.

REST APIs

Remove a notification configuration

To remove an existing notification configuration from your bucket:

Console

You cannot manage Pub/Sub notifications with the Google Cloud console. Use the gcloud CLI or one of the available client libraries instead.

Command line

Use the gcloud storage buckets notifications delete command:

gcloud storage buckets notifications delete projects/_/buckets/BUCKET_NAME/notificationConfigs/NOTIFICATION_ID

Where:

  • BUCKET_NAME is the name of the bucket whose notification configuration you want to delete. For example, my-bucket.

  • NOTIFICATION_ID is the ID number of the configuration you want to delete. For example, 5.

If successful, the response looks similar to the following example:

Completed 1

Once sent, it might take up to 30 seconds for all notifications triggered by the notification configuration to stop.

Client libraries

C++

For more information, see the Cloud Storage C++ API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set up authentication for client libraries.

C#

For more information, see the Cloud Storage C# API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set up authentication for client libraries.

Go

For more information, see the Cloud Storage Go API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set up authentication for client libraries.

Java

For more information, see the Cloud Storage Java API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set up authentication for client libraries.

Node.js

For more information, see the Cloud Storage Node.js API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set up authentication for client libraries.

PHP

For more information, see the Cloud Storage PHP API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set up authentication for client libraries.

To delete a notification configuration for a bucket using PHP, see the Google Cloud Client Library reference documentation.

Python

For more information, see the Cloud Storage Python API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set up authentication for client libraries.

Ruby

For more information, see the Cloud Storage Ruby API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set up authentication for client libraries.

Terraform

To remove the notification configuration you created, run terraform destroy from the folder containing your Terraform file.

REST APIs

JSON API

  1. Have gcloud CLI installed and initialized, which lets you generate an access token for the Authorization header.

  2. Use cURL to call the JSON API with a DELETE notificationConfigs request:

    curl -X DELETE \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/notificationConfigs/NOTIFICATION_ID"

    Where:

    • BUCKET_NAME is the name of the bucket whose notification configuration you want to delete. For example, my-bucket.

    • NOTIFICATION_ID is the ID number of the notification configuration you want to delete. For example, 5.

Once sent, it may take up to 30 seconds for all notifications triggered by the notification configuration to stop.

XML API

You cannot manage Pub/Sub notifications with the XML API.

What's next

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2026-02-17 UTC.