Receive and respond to lifecycle events for Google Workspace subscriptions

This page explains the lifecycle events that you receive for Google Workspace subscriptions, and how you can use the events to maintain an active subscription.

The Google Workspace Events API sends the following types of lifecycle events:

• Suspension events that notify you when your subscription is suspended due to an error.
• Expiration reminder events that notify you that your subscription is expiring soon.
• Expired events that notify you when your subscription expires.

Your app should explicitly handle these lifecycle event types and ignore new event types that might appear in the future.

Lifecycle events from the Google Workspace Events API are structured according to the CloudEvents specification. To learn more, see Structure of Google Workspace events.

Note: If your subscription encounters an error related to its notification endpoint, you might not receive lifecycle events. To learn about and address endpoint errors, you can monitor the endpoint itself. To monitor endpoints that are Google Cloud Pub/Sub topics, see Handle message failures.

Suspension events

When an error occurs for a Google Workspace subscription, the Google Workspace Events API suspends the subscription and prevents it from receiving events. You must resolve any errors with the subscription before reactivating it.

To notify you of a suspension, the Google Workspace Events API sends a lifecycle event with the event type google.workspace.events.subscription.v1.suspended.

After you receive a suspension event, you can learn about the reason for the suspension, resolve any errors, and reactivate the subscription. For details, see Resolve errors and reactivate a Google Workspace subscription.

The following shows a CloudEvent for a lifecycle event about a Google Workspace subscription that was suspended due to the error ENDPOINT_PERMISSION_DENIED:

{
  "id": "EVENT_UUID",
  "source": "//workspaceevents.googleapis.com/subscriptions/SUBSCRIPTION_ID",
  "subject": "//workspaceevents.googleapis.com/subscriptions/SUBSCRIPTION_ID",
  "type": "google.workspace.events.subscription.v1.suspended",
  "time": "2023-06-08T06:50:43.641299Z",
  "spec_version": '1.0',
  "datacontenttype": "application/json",
  "data": {
    "subscription":{
      "name": "subscriptions/SUBSCRIPTION_ID",
      "suspension_reason": "ENDPOINT_PERMISSION_DENIED",
      ...
    }
  }
}

Expiration reminder events

After a subscription expires, the Google Workspace Events API permanently deletes it, and you can't renew or reactivate it.

To notify you of an expiring subscription, the Google Workspace Events API sends lifecycle events 12 hours and one hour before the expiration time. The event type for lifecycle events is google.workspace.events.subscription.v1.expirationReminder.

When you receive an expiration reminder event, you can use the subscriptions.update() method to update the expire time. For details, see Update or renew a Google Workspace subscription.

The following shows a CloudEvent for a lifecycle event about an expiring Google Workspace subscription:

{
  "id": "EVENT_UUID",
  "source": "//workspaceevents.googleapis.com/subscriptions/SUBSCRIPTION_ID",
  "subject": "//workspaceevents.googleapis.com/subscriptions/SUBSCRIPTION_ID",
  "type": "google.workspace.events.subscription.v1.expirationReminder",
  "time": "2023-06-08T06:50:43.641299Z",
  "spec_version": '1.0',
  "datacontenttype": "application/json",
  "data": {
    "subscription":{
      "name": "subscriptions/SUBSCRIPTION_ID",
      "expire_time": "2023-06-08T18:50:43.641299Z",
      ...
    }
  }
}

Subscription expired events

The Google Workspace Events API sends you a lifecycle event when the subcription expires. The event type for this lifecycle event is google.workspace.events.subscription.v1.expired.

The Google Workspace Events API permanently deletes expired subscriptions. If your subscription expires, you can use the subscriptions.create() method to create another subscription. For details, see Create a Google Workspace subscription.

The following shows a CloudEvent for a lifecycle event about an expired Google Workspace subscription:

{
  "id": "EVENT_UUID",
  "source": "//workspaceevents.googleapis.com/subscriptions/SUBSCRIPTION_ID",
  "subject": "//workspaceevents.googleapis.com/subscriptions/SUBSCRIPTION_ID",
  "type": "google.workspace.events.subscription.v1.expired",
  "time": "2023-06-08T07:00:00.000000Z",
  "spec_version": '1.0',
  "datacontenttype": "application/json",
  "data": {
    "subscription":{
      "name": "subscriptions/SUBSCRIPTION_ID",
      "expire_time": "2023-06-08T07:00:00.000000Z",
      ...
    }
  }
}

Related topics

• Structure of Google Workspace events
• Resolve errors and reactivate a subscription
• Update or renew a subscription