The Google Forms API is currently in Restricted Beta. To use the API, apply for access at the Early Adopter Program page.

Set up and receive push notifications

You can use the methods in the Watches collection to receive notifications when data changes in Forms.

This page provides a conceptual overview and instructions for setting up and receiving push notifications.

Overview

The Forms API push notifications feature allows applications to subscribe to notifications when data changes in Forms. Notifications are delivered to a Cloud Pub/Sub topic, usually within minutes of the change.

To receive push notifications, you need to set up a Cloud Pub/Sub topic and provide that topic's name when you create a watch for the appropriate event type.

Below are definitions of key concepts used in this documentation:

  • A target is a place where notifications are sent. The only supported target is a Cloud Pub/Sub topic.
  • An event type is a category of notifications that a third party application can subscribe to. For example, EventType.RESPONSES for new and updated response submissions.
  • A watch is an instruction to the Forms API to deliver notifications for a particular event type on a particular form to a target.

Once you create a watch for an event type on a particular form, that watch's target (which is a Cloud Pub/Sub topic) receives notifications from those events on that form until the watch expires. Your watch lasts a week, but you can extend it at any point before it expires by making a request to watches.renew().

Your Cloud Pub/Sub topic only receives notifications about forms that you can view with the credentials you supply. For example, if the user revokes permission from your application or loses edit access to a watched form, notifications are longer delivered.

Available event types

The Forms API currently offers two categories of events:

  • EventType.SCHEMA, which notifies about edits to a form's content and settings.
  • EventType.RESPONSES, which notifies when form responses (both new and updated) are submitted.

Set up a Cloud Pub/Sub topic

Notifications are delivered to Cloud Pub/Sub topics. From Cloud Pub/Sub, you can receive notifications on a web hook, or by polling a subscription endpoint.

To set up a Cloud Pub/Sub topic, you need to do the following:

  1. Complete the Cloud Pub/Sub Prerequisites.

  2. Set up a Cloud Pub/Sub client.

  3. Review the Cloud Pub/Sub pricing, and enable billing for your Developer Console project.

  4. Create a Cloud Pub/Sub topic in the Developer Console (easiest), via the command line tool (for simple programmatic use) or using the Cloud Pub/Sub API.

    Note that Cloud Pub/Sub only allows a limited number of topics, so using one topic to receive all your notifications ensures you do not hit scaling issues if your application becomes popular.

  5. Create a Subscription in Cloud Pub/Sub, to tell Cloud Pub/Sub how to deliver your notifications.

  6. Finally, before creating watches targeting your topic, you need to grant the Forms notifications service account (forms-notifications@system.gserviceaccount.com) permission to publish to your topic.

Register your application for notifications

Once you have a topic that the Forms API push notifications service account can publish to, you can register for notifications, using the watches.create() method. This method validates that the provided Cloud Pub/Sub topic can be reached by the push notifications service account. The method fails if the push notifications service account cannot reach the topic; for example, if the topic does not exist or you have not granted it publish permission on that topic.

Authorization

Like all calls to the Forms API, calls to watches.create() must be authorized with an authorization token. The token must include a scope that grants read access to the data about which notifications are being sent.

For notifications to be delivered, the application must retain an OAuth grant from the authorized user with the required scopes. If the user disconnects the application, notifications cease and the watch may be suspended with an error.

To resume notifications after regaining authorization, use watches.renew().

Receive notifications

Notifications are encoded with JSON, and contain:

  • The ID of the triggering form
  • The type of event that triggered the notification
  • Other fields set by Cloud Pub/Sub, such as messageId and publishTime

Notifications do not contain detailed form or response data. After each notification is received, a separate API call is required to fetch fresh data. See Suggested usage for how to accomplish this.

The following snippet demonstrates a sample notification for a schema change:

{
  "attributes": {
    "eventType": "SCHEMA"
    "formId": "18Xgmr4XQb-l0ypfCNGQoHAw2o82foMr8J0HPHdagS6g"
  },
  "messageId": "767437830649",
  "publishTime": "2021-03-31T01:34:08.053Z"
}

The following snippet demonstrates a sample notification for a new response:

{
  "attributes": {
    "eventType": "RESPONSES"
    "formId": "18Xgmr4XQb-l0ypfCNGQoHAw2o82foMr8J0HPHdagS6g"
  },
  "messageId": "767467004397",
  "publishTime": "2021-03-31T01:43:57.285Z"
}

Throttling

Notifications are throttled: each watch can receive at most one notification every thirty seconds. This threshold of frequency is subject to change.

Because of throttling, a single notification may correspond to multiple events. In other words, a notification indicates that one or more events have occurred since the last notification.

Reliability

Each watch will be notified at least once after each event in all but extraordinary circumstances. In the vast majority of cases, a notification will be delivered within minutes of an event.

Errors

If notifications for a watch persistently fail to be delivered, the watch state becomes SUSPENDED and the watch's errorType field is set. To reset a suspended watch's state to ACTIVE and resume notifications, use watches.renew().

Suggested usage

  • Use a single Cloud Pub/Sub topic as the target of many watches.
  • When receiving a notification on a topic, the form ID is included in the notification payload. Use it with the event type to know what data to fetch and which form to fetch it from.
  • To fetch updated data after a notification with EventType.RESPONSES, call forms.responses.list().
    • Set filter on the request to timestamp > the timestamp of the last response you fetched.
  • To fetch updated data after a notification with EventType.SCHEMA, call forms.get().