To set up a notification channel for messages about changes to a
particular resource, send a
POST
request to the
watch
method for the resource.
Each notification channel is associated both with a particular user and
a particular resource (or set of resources). A
watch
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 a
channels
resource to start watching for changes to a single
files
resource using the
files.watch
method:
POST https://www.googleapis.com/drive/v3/files/
fileId
/watch
Authorization: Bearer
CURRENT_USER_AUTH_TOKEN
Content-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 a
channels
resource to start watching for all
changes
using the
changes.watch
method:
POST https://www.googleapis.com/drive/v3/changes/watch
Authorization: Bearer
CURRENT_USER_AUTH_TOKEN
Content-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 each
watch
request, you must provide these fields:
-
An
id
property 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-Id
HTTP header of every notification
message that you receive for this channel.
-
A
type
property string set to the value
web_hook
.
-
An
address
property 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 your
watch
request:
-
A
token
property 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-Token
HTTP 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=mobile
Don't include sensitive data such as OAuth tokens.
-
An
expiration
property string set to a
Unix 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-Expiration
HTTP header (in human-readable
format) in every notification message that your
application receives for this channel.
For more details on the request, refer to the
watch
method
for the
files
and
changes
methods in the API Reference.
Watch response
If the
watch
request successfully creates a notification
channel, it returns an HTTP
200 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 the
resourceId
and
resourceUri
to identify the resource being watched on this
notification channel.
You can pass the returned information to other notification channel
operations, such as when you want to
stop receiving
notifications
.
For more details on the response, refer to the
watch
method for the
files
and
changes
methods in the API Reference.
Sync message
After creating a notification channel to watch a resource, the
Google Drive API sends a
sync
message to indicate that
notifications are starting. The
X-Goog-Resource-State
HTTP
header value for these messages is
sync
. Due to network
timing issues, it's possible to receive the
sync
message
even before you receive the
watch
method response.
It's safe to ignore the
sync
notification, but you can
also use it. For example, if you decide you don't want to keep
the channel, you can use the
X-Goog-Channel-ID
and
X-Goog-Resource-ID
values in a call to
stop receiving notifications
. You can also use the
sync
notification to do some initialization to prepare for
later events.
The format of
sync
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-value
X-Goog-Channel-Token: channel-token-value
X-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-resource
X-Goog-Resource-URI: version-specific-URI-of-the-watched-resource
X-Goog-Resource-State: sync
X-Goog-Message-Number: 1
Sync messages always have an
X-Goog-Message-Number
HTTP
header value of
1
. 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 a
Unix timestamp
(in milliseconds) in the information returned by the
watch
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 the
X-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
the
watch
method. As always, you must use a unique value for
the
id
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.