Push Notifications

Overview

The G Suite Reseller API uses the Cloud Pub/Sub API to deliver push notifications about different G Suite subscription events.

Prerequisites

  • Enable the Cloud Pub/Sub API in your developer console project.
  • Familiarize yourself with the pub/sub concepts and data models.
  • If you are going to consume the notification feed via webhooks, you must verify ownership of your domain. You can find the domain verification page in the Google API Console.

Create a topic

To create a topic, you need to register with the G Suite Reseller API via the resellernotify.register method. The resellernotify.register method takes a service account email address as a parameter. Only service accounts authorized by this method can subscribe to your newly created topic.

POST https://www.googleapis.com/apps/reseller/v1/resellernotify/register

{
  "serviceAccountEmailAddress": "reseller@reseller-project.iam.gserviceaccount.com"
}

A successful response returns a HTTP 200 along with a JSON response containing a topic name. This topic name corresponds to your Pub/Sub feed and will be used in the next step to create your subscription.

{
  "topicName": "projects/partner-watch/topics/C0abcdefg"
}

Subsequent calls to the resellernotify.register can be used to authorize other service accounts to use your topic.

Revoke access for a service account

The G Suite Reseller API also provides the ability to unregister service accounts using the resellernotify.unregister endpoint.

POST https://www.googleapis.com/apps/reseller/v1/resellernotify/unregister

{
  "serviceAccountEmailAddress": "reseller@reseller-project.iam.gserviceaccount.com"
}

Subscribe to a topic

Now that the topic has been created, you need to set up how your application will consume your change events. You have two options to choose from:

Push
HTTP POST callback
Pull
Call initiated by your app to pull all spooled changes

To subscribe to your topic, you need to call the Cloud Pub/Sub API. Familiarize yourself with the following terminology:

Topic
A Pub/Sub notification feed. This was created when you called resellernotify.register
Project
The developer console project of the service account used to register.
Subscription
A registration to receive notification from a particular project on a particular topic. You may name this whatever you want, as it is only for your own tracking purposes.
PUT https://pubsub.googleapis.com/v1/projects/<your-project>/subscriptions/<subscription-name>

{
  "topic": "<topic-obtained-earlier>"
  // Only needed for push configurations
  "pushConfig": {
    "pushEndpoint": "https://mysite.com/pushHandler"
  },
}

If you have chosen to use the Push method of consuming notifications, you will also need to provide your Push notification handler endpoint. Please note that this endpoint will need to have been verified in your Developer Console project otherwise the request will fail.

A successful response returns an HTTP 200 status code.

{
  "name": "projects/<your-project>/subscriptions/<subscription-name>",
  "topic": <topic-obtained-earlier>",
  "pushConfig": {
    "pushEndpoint": "https://mysite.com/myhandler"
   },
  "ackDeadlineSeconds": 10
}

Notification formats

The notifications take the following form. The message data is transmitted as a base64 encoded JSON string.

{
  "message": {
    "attirbutes": {},
    "data": "eyJza3VfaWQiOiAiR29vZ2xlLUFwcHMtVW5saW1pdGVkIiwgImV2ZW50X3R5cGUiOiAiU1VCU0NSSVBUSU9OX0NBTkNFTExFRCIsICJjdXN0b21lcl9kb21haW5fbmFtZSI6ICJkb21haW4uY29tIiwgInN1YnNjcmlwdGlvbl9pZCI6ICIxMjM0NTY3IiwgImN1c3RvbWVyX2lkIjogIkMwYWJjZGVmIiwgIm1lc3NhZ2VfaWQiOiAiODY3NTMwOSIsICJwdWJsaXNoX3RpbWUiOiB7InNlY29uZHMiOiAxNDU3NzMxODQ2LCAibmFub3MiOiAzNDkwMDAwMDB9LCAicmVzZWxsZXJfY3VzdG9tZXJfaWQiOiAiQzByZXNlbGxlciJ9",
    "message_id": 1234567891012131
  },
  "subscription": "projects/<your-project>/subscriptions/<subscription-name>"
}

The base64 decoded JSON message.data:

{
  "customer_id": "C0abcdef",
  "customer_domain_name": "domain.com",
  "event_type": "SUBSCRIPTION_CANCELLED",
  "sku_id": "Google-Apps-Unlimited",
  "subscription_id": "1234567",
  // Optional fields depended on event_type
  "subscription_suspension_reasons": [],
  "subscription_cancellation_reason": "REASON"
}

Notification Data Fields

Field Name Explanation
customer_id The ID of the customer whose subscription has been updated.
customer_domain_name The primary domain of the customer.
event_type The type of change that occurred to the subscription. See below for details.
sku_id The SKU of the subscription
subscription_id The ID of the subscription
subscription_suspension_reasons A list of reasons why this subscription was suspended, see below. Will only be populated for event_type of SUBSCRIPTION_SUSPENDED
subscription_cancellation_reason The reason this subscription was cancelled, see below. Will only be populated for event_type of SUBSCRIPTION_CANCELLED

Event Types

Event Type Explanation
NEW_SUBSCRIPTION_CREATED A new subscription was created.
SUBSCRIPTION_TRIAL_ENDED Trial ended for a subscription.
PRICE_PLAN_SWITCHED Customer converts from flexible to annual. This is NOT triggered if there is a commitment->flexible switch as part of renewal.
COMMITMENT_CHANGED Annual commitment was increased or decreased.
SUBSCRIPTION_RENEWED An annual subscription was renewed.
SUBSCRIPTION_SUSPENDED Subscription is suspended. Will populate the subscription_suspension_reasons field.
SUBSCRIPTION_SUSPENSION_REVOKED Suspension was revoked for a previously suspended subscription.
SUBSCRIPTION_CANCELLED Subscription was cancelled. Will populate the subscription_cancellation_reason field. Can also be used to detect transfers.
SUBSCRIPTION_CONVERTED Subscription was converted. e.g. use cases
  • Direct=>Reseller
  • Paid=>Grace
  • Online=>Offline
SUBSCRIPTION_UPGRADE Subscription SKU was switched from G Suite Basic to G Suite Business.
SUBSCRIPTION_DOWNGRADE Subscription SKU was switched from G Suite Business to G Suite Basic.
SEATS_CHANGED Number of seats in use for a Flex account has changed.
LICENSE_ASSIGNMENT_CHANGED License was assigned-to or revoked-from user.

Subscription cancellation reasons

Reason Explanation
TRANSFERRED_OUT The customer has transferred to direct or to another reseller.
PURCHASE_OF_SUBSUMING_SKU The customer has upgraded to a SKU that overrides another.
For example: a customer with G Suite and Drive upgrades to G Suite Business. The Drive subscription would be subsumed.
RESELLER_INITIATED The Reseller cancelled the subscription.
OTHER The subscription was cancelled for some reason other than listed.

Subscription suspension reasons

Reason Explanation
PENDING_TOS_ACCEPTANCE The customer has not logged in and accepted the G Suite Resold Terms of Services.
RENEWAL_WITH_TYPE_CANCEL The customer's commitment ended and their service was cancelled at the end of their term.
RESELLER_INITIATED A manual suspension invoked by a Reseller.
TRIAL_ENDED The customer's trial expired without a plan selected.
OTHER The customer is suspended for an internal Google reason (e.g. abuse or otherwise).

Pub/Sub limitations

The Push notification ordering is not guaranteed. Messages may be delivered multiple times and in extreme situations, not at all. We recommend using reseller.subscriptions.get on all changed subscriptions to pull the current state.

Send feedback about...

G Suite Reseller API
G Suite Reseller API