Push Notifications

This document describes how to use push notifications that inform your application when a resource changes.


The Directory API provides push notifications that let you watch for changes to resources. You can use this feature to improve the performance of your application. 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 Directory 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 Directory API sends a notification message as a POST request to that URL.

Currently, the Directory API supports notifications for changes to the Users resource.

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:

  1. Go to the Domain verification page in the API Console.
  2. Click Add domain.
  3. 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.