Notifications for resource changes
This document describes how to use push notifications that inform yourapplication when a resource changes.
Overview
The Google Drive API provides push notifications that let you monitor changes in resources. You can use this feature to improve the performance of your application. It lets you eliminate the extra network and compute costs involved with polling resources to determine if they have changed. Whenever a watched resource changes, the Google Drive API notifies your application.
To use push notifications, you must do two things:
Set up your receiving URL or "webhook" callback receiver.
This is an HTTPS server that handles the API notification messages that are triggered when a resource changes.
Set up a (notification channel) for each resource endpoint you want to watch.
A channel specifies routing information for notification messages. As part of the channel setup, you must identify the specific URL where you want to receive notifications. Whenever a channel's resource changes, the Google Drive API sends a notification message as a
POSTrequest to that URL. Note: The word "channel" as used in this document refers specifically to a notification channel and not to any other types of channels used in this API or service. Multiple notification channels can be active at the same time for the same resource.
Currently, the Google Drive API supports notifications for changes to thefiles andchanges methods.
Create notification channels
To request push notifications, you must set up a notification channel for each resource you want to monitor. After your notification channels are set up, the Google Drive API informs your application when any watched resource changes.
Make watch requests
Each watchable Google Drive API resource has an associatedwatch method at a URI of the following form:
https://www.googleapis.com/API_NAME/API_VERSION/RESOURCE_PATH/watch
To set up a notification channel for messages about changes to a particular resource, send aPOST request to thewatch method for the resource.
Each notification channel is associated both with a particular user and a particular resource (or set of resources). Awatch request won't be successful unless the current user or service account owns or has permission to access this resource.
Examples
The following code sample shows how to use achannels resource to start watching for changes to a singlefiles resource using thefiles.watch method:
POST https://www.googleapis.com/drive/v3/files/fileId/watchAuthorization: BearerCURRENT_USER_AUTH_TOKENContent-Type: application/json{ "id": "01234567-89ab-cdef-0123456789ab", // Your channel ID. "type": "web_hook", "address": "https://mydomain.com/notifications", // Your receiving URL. ... "token": "target=myApp-myFilesChannelDest", // (Optional) Your files channel token. "expiration": 1426325213000 // (Optional) Your requested channel expiration date and time.}The following code sample shows how to use achannels resource to start watching for allchanges using thechanges.watch method:
POST https://www.googleapis.com/drive/v3/changes/watchAuthorization: BearerCURRENT_USER_AUTH_TOKENContent-Type: application/json{ "id": "4ba78bf0-6a47-11e2-bcfd-0800200c9a77", // Your channel ID. "type": "web_hook", "address": "https://mydomain.com/notifications", // Your receiving URL. ... "token": "target=myApp-myChangesChannelDest", // (Optional) Your changes channel token. "expiration": 1426325213000 // (Optional) Your requested channel expiration date and time.}Required properties
With eachwatch request, you must provide these fields:
An
idproperty string that uniquely identifies this new notification channel within your project. We recommend using a universally unique identifier (UUID) or any similar unique string. Maximum length: 64 characters.The ID value you set is echoed back in the
X-Goog-Channel-IdHTTP header of every notification message that you receive for this channel.A
typeproperty string set to the valueweb_hook.An
addressproperty string set to the URL that listens and responds to notifications for this notification channel. This is your webhook callback URL, and it must use HTTPS.Note that the Google Drive API is able to send notifications to this HTTPS address only if there's a valid SSL certificate installed on your web server. Invalid certificates include:
- Self-signed certificates.
- Certificates signed by an untrusted source.
- Certificates that have been revoked.
- Certificates that have a subject that doesn't match the target hostname.
Optional properties
You can also specify these optional fields with yourwatch request:
A
tokenproperty that specifies an arbitrary string value to use as a channel token. You can use notification channel tokens for various purposes. For example, you can use the token to verify that each incoming message is for a channel that your application created—to ensure that the notification is not being spoofed—or to route the message to the right destination within your application based on the purpose of this channel. Maximum length: 256 characters.The token is included in the
X-Goog-Channel-TokenHTTP header in every notification message that your application receives for this channel.If you use notification channel tokens, we recommend that you:
Use an extensible encoding format, such as URL query parameters. Example:
forwardTo=hr&createdBy=mobileDon't include sensitive data such as OAuth tokens.
An
expirationproperty string set to aUnix timestamp (in milliseconds) of the date and time when you want the Google Drive API to stop sending messages for this notification channel.If a channel has an expiration time, it's included as the value of the
X-Goog-Channel-ExpirationHTTP header (in human-readable format) in every notification message that your application receives for this channel.
files resource and 604800 seconds (1 week) forchanges. If you don’t set theexpiration property in your request, the expiration time defaults to 3600 seconds after the current time.For more details on the request, refer to thewatch method for thefiles andchanges methods in the API Reference.
Watch response
If thewatch request successfully creates a notification channel, it returns an HTTP200 OK status code.
The message body of the watch response provides information about the notification channel you just created, as shown in the example below.
{ "kind": "api#channel", "id": "01234567-89ab-cdef-0123456789ab"", // ID you specified for this channel. "resourceId": "o3hgv1538sdjfh", // ID of the watched resource. "resourceUri": "https://www.googleapis.com/drive/v3/files/o3hgv1538sdjfh", // Version-specific ID of the watched resource. "token": "target=myApp-myFilesChannelDest", // Present only if one was provided. "expiration": 1426325213000, // Actual expiration date and time as UNIX timestamp (in milliseconds), if applicable.}In addition to the properties you sent as part of your request, the returned information also includes theresourceId andresourceUri to identify the resource being watched on this notification channel.
resourceId property is a stable, version-independent identifier for the resource. TheresourceUri property is the canonical URI of the watched resource in the context of the current API version, so it's version-specific.You can pass the returned information to other notification channel operations, such as when you want tostop receiving notifications.
For more details on the response, refer to thewatch method for thefiles andchanges methods in the API Reference.
Sync message
After creating a notification channel to watch a resource, the Google Drive API sends async message to indicate that notifications are starting. TheX-Goog-Resource-State HTTP header value for these messages issync. Due to network timing issues, it's possible to receive thesync message even before you receive thewatch method response.
It's safe to ignore thesync notification, but you can also use it. For example, if you decide you don't want to keep the channel, you can use theX-Goog-Channel-ID andX-Goog-Resource-ID values in a call tostop receiving notifications. You can also use thesync notification to do some initialization to prepare for later events.
The format ofsync messages the Google Drive API sends to your receiving URL is shown below.
POST https://mydomain.com/notifications // Your receiving URL.X-Goog-Channel-ID: channel-ID-valueX-Goog-Channel-Token: channel-token-valueX-Goog-Channel-Expiration: expiration-date-and-time // In human-readable format. Present only if the channel expires.X-Goog-Resource-ID: identifier-for-the-watched-resourceX-Goog-Resource-URI: version-specific-URI-of-the-watched-resourceX-Goog-Resource-State: syncX-Goog-Message-Number: 1
Sync messages always have anX-Goog-Message-Number HTTP header value of1. Each subsequent notification for this channel has a message number that's larger than the previous one, though the message numbers will not be sequential.
Renew notification channels
A notification channel can have an expiration time, with a value determined either by your request or by any Google Drive API internal limits or defaults (the more restrictive value is used). The channel's expiration time, if it has one, is included as aUnix timestamp (in milliseconds) in the information returned by thewatch method. In addition, the expiration date and time is included (in human-readable format) in every notification message your application receives for this channel in theX-Goog-Channel-Expiration HTTP header.
Currently, there's no automatic way to renew a notification channel. When a channel is close to its expiration, you must replace it with a new one by calling thewatch method. As always, you must use a unique value for theid property of the new channel. Note that there's likely to be an "overlap" period of time when the two notification channels for the same resource are active.
Receive notifications
Whenever a watched resource changes, your application receives a notification message describing the change. The Google Drive API sends these messages as HTTPSPOST requests to the URL you specified as theaddress property for this notification channel.
APIs-Google and respect robots.txt directives, as described inAPIs Google User Agent.Interpret the notification message format
All notification messages include a set of HTTP headers that haveX-Goog- prefixes. Some types of notifications can also include a message body.
Headers
Notification messages posted by the Google Drive API to your receiving URL include the following HTTP headers:
| Header | Description |
|---|---|
| Always present | |
| UUID or other unique string you provided to identify this notification channel. |
| Integer that identifies this message for this notification channel. Value is always1 forsync messages. Message numbers increase for each subsequent message on the channel, but they're not sequential. |
| An opaque value identifying the watched resource. This ID is stable across API versions. |
| The new resource state that triggered the notification. Possible values:sync,add,remove,update,trash,untrash, orchange. |
| An API-version-specific identifier for the watched resource. |
| Sometimes present | |
| Additional details about the changes. Possible values:content,parents,children, orpermissions. Not provided withsync messages. |
| Date and time of notification channel expiration, expressed in human-readable format. Only present if defined. |
| Notification channel token that was set by your application, and that you can use to verify the notification source. Only present if defined. |
Notification messages forfiles andchanges are empty.
Examples
Change notification message forfiles resources, which doesn't include a request body:
POST https://mydomain.com/notifications // Your receiving URL.Content-Type: application/json; utf-8Content-Length: 0X-Goog-Channel-ID: 4ba78bf0-6a47-11e2-bcfd-0800200c9a66X-Goog-Channel-Token: 398348u3tu83ut8uu38X-Goog-Channel-Expiration: Tue, 19 Nov 2013 01:13:52 GMTX-Goog-Resource-ID: ret08u3rv24htgh289gX-Goog-Resource-URI: https://www.googleapis.com/drive/v3/files/ret08u3rv24htgh289gX-Goog-Resource-State: updateX-Goog-Changed: content,propertiesX-Goog-Message-Number: 10
Change notification message forchanges resources, which includes a request body:
POST https://mydomain.com/notifications // Your receiving URL.Content-Type: application/json; utf-8Content-Length: 118X-Goog-Channel-ID: 8bd90be9-3a58-3122-ab43-9823188a5b43X-Goog-Channel-Token: 245t1234tt83trrt333X-Goog-Channel-Expiration: Tue, 19 Nov 2013 01:13:52 GMTX-Goog-Resource-ID: ret987df98743md8gX-Goog-Resource-URI: https://www.googleapis.com/drive/v3/changesX-Goog-Resource-State: changedX-Goog-Message-Number: 23{ "kind": "drive#changes"}Respond to notifications
To indicate success, you can return any of the following status codes:200,201,202,204, or102.
If your service usesGoogle's API client library and returns500,502,503, or504, the Google Drive API retries withexponential backoff. Every other return status code is considered to be a message failure.
Understand Google Drive API notification events
This section provides details on the notification messages you can receive when using push notifications with the Google Drive API.
| Delivered when | ||
|---|---|---|
sync | files,changes | A channel was successfully created. You can expect to start receiving notifications for it. |
add | files | A resource was created or shared. |
| files | An existing resource was deleted or unshared. |
| files | One or more properties (metadata) of a resource have been updated. |
| files | A resource has been moved to the trash. |
| files | A resource has been removed from the trash. |
| changes | One or more changelog items have been added. |
Forupdate events, theX-Goog-Changed HTTP header might be provided. That header contains a comma-separated list that describes the types of changes that have occurred.
| Change type | Indicates |
|---|---|
content | The resource content has been updated. |
properties | One or more resource properties have been updated. |
parents | One or more resource parents have been added or removed. |
children | One or more resource children have been added or removed. |
permissions | The resource permissions have been updated. |
Example withX-Goog-Changed header:
X-Goog-Resource-State: updateX-Goog-Changed: content, permissions
Stop notifications
Theexpiration property controls when the notifications stop automatically. You can choose to stop receiving notifications for a particular channel before it expires by calling thestop method at the following URI:
https://www.googleapis.com/drive/v3/channels/stop
This method requires that you provide at least the channel'sid and theresourceId properties, as shown in the example below. Note that if the Google Drive API has several types of resources that havewatch methods, there's only onestop method.
Only users with the right permission can stop a channel. In particular:
- If the channel was created by a regular user account, only the same user from the same client (as identified by the OAuth 2.0 client IDs from the auth tokens) who created the channel can stop the channel.
- If the channel was created by a service account, any user from the same client can stop the channel.
The following code sample shows how to stop receiving notifications:
POST https://www.googleapis.com/drive/v3/channels/stop Authorization: BearerCURRENT_USER_AUTH_TOKENContent-Type: application/json{ "id": "4ba78bf0-6a47-11e2-bcfd-0800200c9a66", "resourceId": "ret08u3rv24htgh289g"}Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2025-12-11 UTC.