Subscribe to events using the Google Workspace Events API

This page provides an overview of the Google Workspace Events API and explains how you can use the API to subscribe to events across Google Workspace.

Google Workspace events represent changes to Google Workspace resources, such as when resources are created, updated, or deleted. Your app can subscribe to a Google Workspace resource so that you receive relevant events that you're interested in.

How your app receives events

To let your app receive Google Workspace events, you use the Google Workspace Events API to create subscriptions to Google Workspace resources.

Illustration of how the Google Workspace Events API delivers events.

Here's how the Google Workspace Events API delivers events to your app through a subscription:

Your app subscribes to a resource in a Google Workspace application, such as a Google Chat space.
The resource that you're subscribed to changes.
The Google Workspace application delivers an event to a topic in Google Cloud Pub/Sub, which serves as the notification endpoint for your Google Workspace subscription. The event contains data about what changed in the resource.
Your app processes the Google Cloud Pub/Sub message that contains the event, and if necessary, takes action.

Important terminology

The following is a list of common terms used in the Google Workspace Events API:

Google Workspace event

A change to a Google Workspace resource. Events are formatted using the CloudEvents specification, and can be either a subscription event or a lifecycle event:

Subscription event: A change to the Google Workspace resource that you're monitoring, such as a new message in a Google Chat space. You can specify how much detail you want to receive about the resource that changed. For details, see Structure of Google Workspace events.
Lifecycle event: An event about your Google Workspace subscription. Lifecycle events notify you about issues and the state of your subscription so that you can avoid missing subscription events. By default, your subscription always receives lifecycle events. For details, see Lifecycle events for Google Workspace subscriptions.

Google Workspace subscription

A named entity that monitors a resource from a Google Workspace application. A subscription is represented by a Subscription resource. A subscription is defined by the following information:

Target resource: The Google Workspace resource that you want to monitor. This resource is represented in the targetResource field of the Google Workspace subscription. Each subscription can only monitor one resource. To see which Google Workspace resources the Google Workspace Events API supports, see Supported Google Workspace events.
Event types: The types of changes that you want to be notified about for the target resource. For example, if you've subscribed to a Google Chat space, you can choose whether to receive events about the space and its child resources, such as memberships and messages.
Notification endpoint: The endpoint where the Google Workspace subscription receives events. The Google Workspace Events API supports Google Cloud Pub/Sub topics as a notification endpoint. To learn more about using Google Cloud Pub/Sub, see the Google Cloud Pub/Sub documentation.
Payload options: The event data that you want to receive about changed resources.

Supported Google Workspace events

The events that your app can receive events depend on the target resource of your subscription. The following table displays the supported events for each possible target resource.

Target resource	Format	Supported events	Limitations (if applicable)
Google Chat
Google Chat spaces	`//chat.googleapis.com/spaces/SPACE_ID`	Messages Memberships Reactions Space For details, see Subscribe to Google Chat events.	The Google Chat user that authorizes the subscription must be a member of the space through their Google Workspace or Google Account.
Google Chat users	`//cloudidentity.googleapis.com/users/USER_ID`	Memberships For details, see Subscribe to Google Chat events.	The subscription only receives events about the user that authorized the subscription. A user can't authorize a subscription on behalf of other users.
Google Meet
Google Meet meeting spaces	`//meet.googleapis.com/spaces/SPACE_ID`	Conferences Participant sessions Recordings Transcripts For details, see Subscribe to Google Meet events.
Google Meet users	`//cloudidentity.googleapis.com/users/USER_ID`	Conferences Participant sessions Recordings Transcripts For details, see Subscribe to Google Meet events.	The subscription receives events about meeting spaces where the user is one of the following: The owner of the meeting space. The organizer of the Google Calendar event associated with the meeting space.

Structure of Google Workspace events

Google Workspace events follow the CloudEvents specification, which is an industry-standard way of describing event data. Google Workspace events contain the following:

Attributes of the CloudEvent.
Data about the Google Workspace resource that changed as a result of the event

The following section explains the structure of the attributes and data for Google Workspace events.

CloudEvent attributes

Google Workspace events contain the following required CloudEvents attributes:

Attribute	Description	Example
`datacontenttype`	The type of data that has been passed in the event.	`application/json`
`id`	An identifier for the CloudEvent.	`spaces/AAAABBBBBBB/spaceEvents/ABCDEFGHIJKLMNO`
`source`	The source of the event. For Google Workspace events, this is the full resource name of the subscription.	`//workspaceevents.googleapis.com/subscriptions/chat-spaces-abcdefg`
`specversion`	The CloudEvents specification version used for this event.	`1.0`
`subject`	The Google Workspace resource where the event occurred.	`//chat.googleapis.com/spaces/AAAABBBBBBB`
`time`	The timestamp when the event occurred, in RFC 3339 format.	`2023-09-07T21:37:36.260127Z`
`type`	The type of Google Workspace event.	`google.workspace.chat.message.v1.created`

Event data

Event data is a payload that represents a change to your subscription's target resource, including child resources of the target resource. In your subscription, you can specify whether you want the payload to include data about the changed resource, or just the name of the changed resource.

For example, if you have a subscription to a Chat space, you can receive events about new messages in the space. For events about new messages, the event data contains a payload with the Chat spaces.message resource that was created.

When you create a subscription, you can specify how much resource data is included in the events that your app receives:

Include resource data: Contains some or all fields of the changed resource. If you choose to include resource data, your subscription duration is limited to up to 4 hours, or 24 hours if you use domain-wide delegation.
Exclude resource data: Contains only the name of the changed resource. Your subscription duration is up to 7 days. To get details about the event, you can query the resource using the resource name.

These options for event data are represented in the payloadOptions field of your subscription.

Events as Google Cloud Pub/Sub messages

The Google Workspace Events API subscriptions use Google Cloud Pub/Sub topics as the notification endpoint that receives Google Workspace events. The events are encoded as Google Cloud Pub/Sub messages. Your app can process the Google Cloud Pub/Sub message to take action or respond to the event.

The following example shows a Google Cloud Pub/Sub message that contains an event about an updated message in a Chat space:

 {
    "message":
    {
        "attributes":
        {
            "ce-datacontenttype": "application/json",
            "ce-id": "spaces/SPACE_ID/spaceEvents/SPACE_EVENT_ID",
            "ce-source": "//workspaceevents.googleapis.com/subscriptions/SUBSCRIPTION_ID",
            "ce-specversion": "1.0",
            "ce-subject": "//chat.googleapis.com/spaces/SPACE_ID",
            "ce-time": "2023-09-07T21:37:53.274191Z",
            "ce-type": "google.workspace.chat.message.v1.updated"
        },
        "data": "EVENT_DATA",
        "messageId": "PUBSUB_MESSAGE_ID",
        "orderingKey": "//workspaceevents.googleapis.com/subscriptions/SUBSCRIPTION_ID",
        "publishTime": "2023-09-07T21:37:53.713Z"
    }
}

Note the following fields:

attributes: Attributes for the CloudEvent, which include the event type. In this case, the event is about an updated message in the space.
data: The event data with details about the updated spaces.message resource, formatted as a Base64-encoded string.
messageId: The identifier for the Google Cloud Pub/Sub message.

To learn more about how CloudEvents are specified in Google Cloud Pub/Sub messages, see Google Cloud Pub/Sub Protocol Binding for CloudEvents.

Subscribe to Google Chat events
Lifecycle events for Google Workspace subscriptions
Choose Google Workspace Events API scopes
Create a Google Workspace subscription