Push notifications

Required properties

With each watch request, you must provide these fields:

• An id property string that uniquely identifies this new notification channel within your project. We recommend using 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 Admin SDK API is able to send notifications to this HTTPS address only if there's 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 various 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

  • Don't include sensitive data such as OAuth tokens.

• An expiration property string set to a Unix timestamp (in milliseconds) of the date and time when you want the Admin SDK API to stop sending messages for this notification channel.

  If a channel has an expiration time, it's included as the value of the X-Goog-Channel-Expiration HTTP header (in human-readable format) in every notification message that your application receives for this channel.

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://admin.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 notification channel to watch a resource, the Admin SDK API sends a sync message to indicate that notifications are starting. The X-Goog-Resource-State HTTP header value for these messages is sync. Due to network timing issues, it's possible to receive the sync message even before you receive the watch method response.

It's safe to ignore the sync notification, but you can also use it. For example, if you decide you don't 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 Admin SDK 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 the 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 has a message number that's larger than the previous one, though the message numbers will not be sequential.

Renew notification channels

A notification channel can have an expiration time, with a value determined either by your request or by any Admin SDK 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 milliseconds) 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's no automatic way to renew a notification channel. When a channel is close to its expiration, you must replace it with 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's likely to be an "overlap" period of time when the two notification channels for the same resource are active.

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

Notification messages for Activities contain the following information in the request body:

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://admin.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
        }
      ]
    }
  ]
}

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://admin.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"
        }
      ]
    }
  ]
}

Respond 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 Admin SDK API retries with exponential backoff. Every other return status code is considered to be a message failure.

Understand Admin SDK API notification events

This section provides details on the notification messages you can receive when using push notifications with the Admin SDK 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:

• admin
• calendar
• drive
• groups
• login
• mobile
• saml
• token
• user_accounts