This document describes how to use push notifications that inform yourapplication when a resource changes.
You can use the Google Calendar API to find and view public calendar events. If you're authorized, you can also access and modify private calendars and events on those calendars. Use the Google Calendar API to achieve deeper integration with Google Calendar. Mobile apps, Web apps, and other systems can create, display, or sync with Calendar data. Organizing has never been this easy!! CalendarPro is a simple Desktop client application for Google calendars, with an intuitive design. Now, it's so easy to get every event organized.
Overview
Posterino 3 75. The Google Calendar API provides push notifications that let you watch for changes to resources. You can use this feature to improve the performance of your application. Subtitles 3 2 5 download free. It allows you to eliminate the extra network and compute costs involved with polling resources to determine if they have changed. Whenever a watched resource changes, the Google Calendar API notifies your application.
To use push notifications, you need to do three things:
- Register the domain of your receiving URL.For example, if you plan to use https://mydomain.com/notifications as your receiving URL, you need to register https://mydomain.com.
- 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 identify the specific URL where you want to receive notifications. Whenever a channel's resource changes, the Google Calendar API sends a notification message as a
POST
request to that URL.
![Calendarpro Calendarpro](https://s1.mzstatic.com/us/r30/Purple127/v4/f6/e6/ca/f6e6ca6e-5188-7267-2e04-f537595e98aa/screen800x500.jpeg)
Currently, the Google Calendar API supports notifications for changes to the Acl, CalendarList, Events, and Settings resources.
Registering your domain
Before you can set up a push notification channel, you must register the domain for any URLs you plan to use to receive push notification messages. In addition, before you register a domain, you must first verify that you own it. This step is an abuse-prevention measure to stop anyone from using push to send messages to someone else’s domain.
Step 1: Verify that you own the domain
Before you can register your domain, you need to verify that you own it. Complete the site verification process using Search Console. For more details, see the site verification help documentation.
Step 2: Register your domain
To register a verified domain name as one of the allowed domains for your project, do the following:
- Go to the Domain verification page in the API Console.
- Click Add domain.
- Fill in the form, then again click Add domain.
At this point, the Google API Console checks all domains in the list against the ones that you have verified in Search Console. Assuming that you properly verified all the domains, the page updates to show your new list of allowed domains. You now can use any of these domains to receive push notifications.
Creating notification channels
To request push notifications, you need to set up a notification channel for each resource you want to watch. After your notification channels are set up, the Google Calendar API will inform your application when any watched resource changes.
Making watch requests
Each watchable Google Calendar API resource has an associated
watch
method at a URI of the following form: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 will not be successful unless the current user owns or has permission to access this resource.Example
Start watching for changes to a collection of events on a given calendar:
Required properties
With each
watch
request, you need to provide:- An
id
property string that uniquely identifies this new notification channel within your project. We recommend that you use a universally unique identifier (UUID) or any similar unique string. Maximum length: 64 characters.The ID value you set is echoed back in theX-Goog-Channel-Id
HTTP header of every notification message that you receive for this channel. - A
type
property string set to the valueweb_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 Calendar API will be able to send notifications to this HTTPS address only if there is 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.
Important: Before you can use a particular URL as the
address
value, you must first register its domain in the Google API Console.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 any of a variety of 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 theX-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
- Do not include sensitive data such as OAuth tokens.
- An
expiration
property string set to a Unix timestamp (in ms) of the date and time when you want the Google Calendar API to stop sending messages for this notification channel.If a channel has an expiration time, it is included as the value of theX-Goog-Channel-Expiration
HTTP header (this time 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 Acl, CalendarList, Events, and Settings resources 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.
In addition to the properties you sent as part of your request, the returned information also includes the
Note: The resourceId
and resourceUri
to identify the resource being watched on this notification channel.resourceId
property is a stable, version-independent identifier for the resource. The resourceUri
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 to stop receiving notifications.
For more details on the response, refer to the
watch
method for the Acl, CalendarList, Events, and Settings resources in the API Reference.Sync message
After creating a new notification channel to watch a resource, the Google Calendar API sends a
sync
message to indicate that notifications are starting. The X-Goog-Resource-State
HTTP header value for these messages is sync
. Because of network timing issues, it is possible to receive the sync
message even before you receive the watch
method response.Calendarpro 3 3 – Google Calendar Application Form
It is safe to ignore the
sync
notification, but you can also make use of it. For example, if you decide you do not 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 Calendar API sends to your receiving URL is shown below.Sync messages always have an
X-Goog-Message-Number
HTTP header value of 1. Each subsequent notification for this channel will have a message number that is larger than the previous one, though the message numbers will not be sequential.Renewing notification channels
A notification channel can have an expiration time, with a value determined either by your request or by any Google Calendar 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 ms) 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 is no automatic way to renew a notification channel. When a channel is close to its expiration, you must create 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 is likely to be an 'overlap' period of time when the two notification channels for the same resource are active.Receiving notifications
Whenever a watched resource changes, your application will receive a notification message describing the change. The Google Calendar API sends these messages as HTTPS
Note: These notification delivery HTTPS requests specify a user agent of POST
requests to the URL you specified as the 'address' for this notification channel.Google Calendar
APIs-Google
and respect robots.txt directives, as described in APIs Google User Agent.Understanding the notification message format
All notification messages include a set of HTTP headers that have
X-Goog-
prefixes. Some types of notifications can also include a message body.Headers
Notification messages posted by the Google Calendar 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 always 1 for sync messages. Message numbers increase for each subsequent message on the channel, but they are not sequential. |
| An opaque value that identifies the watched resource. This ID is stable across API versions. |
| The new resource state, which triggered the notification. Possible values: sync , exists , or not_exists . |
| An API-version-specific identifier for the watched resource. |
Sometimes present | |
| 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 source of notification. Only present if defined. |
Notification messages posted by the Google Calendar API to your receiving URL do not include a message body.
Examples
Change notification message for modified collection of events:
Responding to notifications
To indicate success, you can return any of the following status codes:
200
, 201
, 202
, 204
, or 102
. If your service uses Google's API client library and returns
500
,502
, 503
, or 504
, the Google Calendar API retries with exponential backoff. Every other return status code is considered to be a message failure.Understanding Google Calendar API notification events
This section provides details on the notification messages you can receive when using push notifications with the Google Calendar API.
Delivered when | ||
---|---|---|
sync | ACLs, Calendar lists, Events, Settings. | A new channel was successfully created. You can expect to start receiving notifications for it. |
exists | ACLs, Calendar lists, Events, Settings. | There was a change to a resource. Possible changes include the creation of a new resource, or the modification or deletion of an existing resource. |
Stopping notifications
The expiration time is when the notifications stop automatically. You can choose to stop receiving notifications for a particular channel before it expires by calling the
stop
method at the following URI:This method requires that you provide at least the channel’s
id
and the resourceId
properties, as shown in the example below. Note that even if the Google Calendar API has several types of resources that have watch
methods, there is only one stop
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 users from the same client can stop the channel.
Special Considerations
When working with push notifications, keep the following in mind:
Events and ACLs are per-calendar If you want to get notified about all event or ACL changes for calendars A and B, you need to separately subscribe to the events/ACL collections for A and for B.
Settings and calendar lists are per-user Settings and calendar lists only have one collection per user, so you can subscribe just once.
![Calendar Calendar](https://data.apksum.com/d2/mikado.bizcalpro/screenhost/3.png)
Also, you won’t be notified when you gain access to a new collection (for example, a new calendar) although you will be notified if that calendar is added to the calendar list (assuming you are subscribed to the calendar list collection).
Notifications are not 100% reliable. Expect a small percentage of messages to get dropped under normal working conditions. Make sure to handle these missing messages gracefully, so that the application still syncs even if no push messages are received.