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 Google 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.
  • 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 no longer delivered.

Available event types

The Google 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.

Notification responses

Notifications are encoded with JSON and contain:

  • The ID of the triggering form
  • The ID of the triggering watch
  • 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",
    "watchId": "892515d1-a902-444f-a2fe-42b718fe8159"
  },
  "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",
    "watchId": "5d7e5690-b1ff-41ce-8afb-b469912efd7d"
  },
  "messageId": "767467004397",
  "publishTime": "2021-03-31T01:43:57.285Z"
}

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, 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 Google Cloud console project.

  4. Create a Cloud Pub/Sub topic one of three ways: