Push Notifications

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

Overview

The Reports 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 Reports 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 Reports API sends a notification message as a POST request to that URL.

Currently, the Reports API supports notifications for changes to the Activities 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.

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 Reports API will inform your application when any watched resource changes.

Making watch requests

Each watchable Reports API resource has an associated watch method at a URI of the following form:

https://www.googleapis.com/apiName/apiVersion/resourcePath/watch

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 or service account owns or has permission to access this resource.

Examples

All watch requests for the Activities resource have the general form:

POST https://www.googleapis.com/admin/reports/v1/activity/users/userKey or all/applications/applicationName/watch
Authorization: Bearer auth_token_for_current_user
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 channel token.
  "payload": true, // (Optional) Whether to include the payload (message body) in notifications.
  "expiration": 3600 // (Optional) Your requested channel expiration time.
}

You can use the userKey, applicationName, eventName, and filters parameters to only receive notifications for specific events, users, or applications.

Note: The following examples omit the request body for clarity.

Watch for all admin activities:

POST https://www.googleapis.com/admin/reports/v1/activity/users/all/applications/admin/watch

Watch for all docs activities:

POST https://www.googleapis.com/admin/reports/v1/activity/users/all/applications/docs/watch

Watch for a specific user's admin activity:

POST https://www.googleapis.com/admin/reports/v1/activity/users/liz@example.com/applications/admin/watch

Watch for a specific event, such as changing a user's password:

POST https://www.googleapis.com/admin/reports/v1/activity/users/all/applications/admin/watch?eventName=CHANGE_PASSWORD

Watch for changes to a specific document:

POST https://www.googleapis.com/admin/reports/v1/activity/users/all/applications/docs/watch?eventName=EDIT&filters==doc_id=123456abcdef

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 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 Reports 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.

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 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

    • 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 Reports API to stop sending messages for this notification channel.

    If a channel has an expiration time, it is included as the value of the X-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 Activities resource 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": "reportsApiId", // ID you specified for this channel.
  "resourceId": "o3hgv1538sdjfh", // ID of the watched resource.
  "resourceUri": "https://www.googleapis.com/admin/reports/v1/activity/userKey/applications/applicationName", // Version-specific ID of the watched resource.
  "token": "target=myApp-myFilesChannelDest", // Present only if one was provided.
  "expiration": 3600, // Actual expiration time as Unix timestamp (in ms), 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 Activities resource in the API Reference.

Sync message

After creating a new notification channel to watch a resource, the Reports 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.

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 Reports 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 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 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 Reports 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 Reports API sends these messages as HTTPS POST requests to the URL you specified as the "address" for this notification channel.

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 Reports API to your receiving URL include the following HTTP headers:

Header Description
Always present
X-Goog-Channel-ID UUID or other unique string you provided to identify this notification channel.
X-Goog-Message-Number 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.
X-Goog-Resource-ID An opaque value that identifies the watched resource. This ID is stable across API versions.
X-Goog-Resource-State The new resource state, which triggered the notification. Possible values: sync or an event name.
X-Goog-Resource-URI An API-version-specific identifier for the watched resource.
Sometimes present
X-Goog-Channel-Expiration Date and time of notification channel expiration, expressed in human-readable format. Only present if defined.
X-Goog-Channel-Token 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 for Activities contain the following information in the request body:

Property Description
kind Identifies this as an Activity resource. Value: the fixed string "admin#reports#activity".
id Unique identifier the activity record.
id.time Time of occurrence of the activity. This is in UNIX epoch time in seconds.
id.uniqueQualifier Unique qualifier if multiple events have the same time.
id.applicationName Application name to which the event belongs. The possible values include:
id.customerId The unique identifier for a G Suite account.
actor User doing the action.
actor.callerType The type of author who performed the activity listed in the report. In this verson of the API, the callerType is the USER or OAuth 2LO entity request who performed the action listed in the report .
actor.email The primary email address of the user whose activites are being reported.
actor.profileId The user's unique G Suite profile ID.
ownerDomain Domain of Admin console or the Docs application's document owner. This is the domain that is affected by the report's event.
ipAddress IP address of the user doing the action. This is the Internet Protocol (IP) address of the user when logging into G Suite which may or may not reflect the user's physical location. For example, the IP address can be the user's proxy server's address or a virtual private network (VPN) address. The API supports IPv4 and IPv6.
events[] Activity events in the report.
events[].type Type of event. The G Suite service or feature that an administrator changes is identified in the type property which identifies an event using the eventName property.
events[].name Name of the event. This is the specific name of the activity reported by the API. And each eventName is related to a specific G Suite service or feature which the API organizes into types of events.
For eventName request parameters in general:
  • If no eventName is given, the report returns all possible instances of an eventName.
  • When you request an eventName, the API's response returns all activities which contain that eventName. It is possible that the returned activities will have other eventName properties in addition to the one requested.
events[].parameters[] Parameter value pairs for various applications.
events[].parameters[].name The name of the parameter.
events[].parameters[].value String value of the parameter.
events[].parameters[].intValue Integer value of the parameter.
events[].parameters[].boolValue Boolean value of the parameter.

Examples

Notification messages for Activity resource events have the general form:

POST https://mydomain.com/notifications // Your receiving URL.
Content-Type: application/json; utf-8
Content-Length: 0
X-Goog-Channel-ID: reportsApiId
X-Goog-Channel-Token: 398348u3tu83ut8uu38
X-Goog-Channel-Expiration: Tue, 29 Oct 2013 20:32:02 GMT
X-Goog-Resource-ID:  ret08u3rv24htgh289g
X-Goog-Resource-URI: https://www.googleapis.com/admin/reports/v1/activity/userKey/applications/applicationName
X-Goog-Resource-State:  eventName
X-Goog-Message-Number: 10

{
  "kind": "admin#reports#activity",
  "id": {
    "time": datetime,
    "uniqueQualifier": long,
    "applicationName": string,
    "customerId": string
  },
  "actor": {
    "callerType": string,
    "email": string,
    "profileId": long
  },
  "ownerDomain": string,
  "ipAddress": string,
  "events": [
    {
      "type": string,
      "name": string,
      "parameters": [
        {
          "name": string,
          "value": string,
          "intValue": long,
          "boolValue": boolean
        }
      ]
    }
  ]
}

An example of an admin activity event:

POST https://mydomain.com/notifications // Your receiving URL.
Content-Type: application/json; utf-8
Content-Length: 596
X-Goog-Channel-ID: reportsApiId
X-Goog-Channel-Token: 245t1234tt83trrt333
X-Goog-Channel-Expiration: Tue, 29 Oct 2013 20:32:02 GMT
X-Goog-Resource-ID:  ret987df98743md8g
X-Goog-Resource-URI: https://www.googleapis.com/admin/reports/v1/activity/users/all/applications/admin?alt=json
X-Goog-Resource-State:  CREATE_USER
X-Goog-Message-Number: 23

{
  "kind": "admin#reports#activity",
  "id": {
    "time": "2013-09-10T18:23:35.808Z",
    "uniqueQualifier": "-0987654321",
    "applicationName": "admin",
    "customerId": "ABCD012345"
  },
  "actor": {
    "callerType": "USER",
    "email": "admin@example.com",
    "profileId": "0123456789987654321"
  },
  "ownerDomain": "apps-reporting.example.com",
  "ipAddress": "192.0.2.0",
  "events": [
    {
      "type": "USER_SETTINGS",
      "name": "CREATE_USER",
      "parameters": [
        {
          "name": "USER_EMAIL",
          "value": "liz@example.com"
        }
      ]
    }
  ]
}

Responding to notifications

To indicate success, you can return any of the following status codes: 200, 201, 202, 204, or 102. If your service returns 500, 502, 503, or 504, the Reports API will retry with exponential backoff.

Every other return status code is considered to be a message failure and the Reports API will not retry this particular notification.

Understanding Reports API notification events

This section provides details on the notification messages you can receive when using push notifications with the Reports API.

Reports API push notifications contain two types of messages: sync messages and event notifications. The message type is indicated in the X-Goog-Resource-State HTTP header. Possible values for event notifications are the same as for the activities.list method. Each application has unique events:

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:

https://www.googleapis.com/admin/reports_v1/channels/stop

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 Reports 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 identifed 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.
POST https://www.googleapis.com/admin/reports_v1/channels/stop
Authorization: Bearer {auth_token_for_current_user}
Content-Type: application/json

{
  "id": "4ba78bf0-6a47-11e2-bcfd-0800200c9a66",
  "resourceId": "ret08u3rv24htgh289g"
}