Page Summary

outlined_flag

• The Google Workspace Events API enables you to subscribe to changes in Google Workspace resources like Google Chat and Google Meet, receiving notifications when resources are created, updated, or deleted.

• Your app receives events through Google Cloud Pub/Sub after subscribing to a specific Google Workspace resource, enabling it to react to changes in real-time.

• You can customize your subscriptions to receive detailed resource data or only resource names, impacting subscription duration and the level of information provided in event notifications.

• Google Workspace events adhere to the CloudEvents standard, providing structured data about the change, including attributes like event type, source, and timestamp.

• Supported Google Workspace events include changes to Chat spaces, messages, memberships, Meet conferences, recordings, and more, offering flexibility in monitoring specific resource activities.

This page provides an overview of the Google Workspace Events API and explains howyou 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 subscribeto a Google Workspace resource so that you receive relevant events that you'reinterested in.

How your app receives events

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

In the following example, here's how the Google Workspace Events API deliversevents to a Google Chat app through a subscription:

1. A Chat app subscribes to a Chat space.
2. The Chat space changes. For example, a new message is postedin the space.
3. Chat delivers an event to a topic inGoogle Cloud Pub/Sub,which serves as the notification endpoint for the subscription. The eventcontains data about what changed. For example, for an event about a newmessage, the event contains details about theMessage resource that'screated.
4. The Chat app processes the Google CloudPub/Sub message that contains the event, and if necessary, takes action.

Important terminology

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

Google Workspace event

A change to a Google Workspace resource. Events are formatted using theCloudEventsspecification, and can be either asubscription event oralifecycle 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 muchdetail you want to receive about the resource that changed. For details, seeStructure of Google Workspace events.

Lifecycle event

An event about your Google Workspace subscription. Lifecycle eventsnotify you about issues and the state of your subscription so that you canavoid missing subscription events. By default, your subscription alwaysreceives lifecycle events. For details,seeLifecycle events for Google Workspace subscriptions.

Google Workspace subscription

A named entity that monitors a resource from a Google Workspaceapplication. A subscription is represented by aSubscriptionresource. A subscription is defined by the following information:

Target resource

The Google Workspace resource that you want to monitor.This resource is represented in thetargetResource field of theGoogle Workspace subscription. Each subscription can onlymonitor one resource. To see which Google Workspace resources theGoogle Workspace Events API supports, seeSupported Google Workspace events.

Event types

The types of changes that you want to be notified about forthe target resource. For example, if you've subscribed to aGoogle Chat space, you can choose whether to receive events aboutthe space and its child resources, such as memberships and messages.

Notification endpoint

The endpoint where theGoogle Workspace subscription receives events. TheGoogle Workspace Events API supports Google Cloud Pub/Sub topics asa notification endpoint. To learn more about using Google Cloud Pub/Sub,see theGoogle Cloud Pub/Sub documentation.

Payload options

Theevent 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 ofyour subscription. The following table displays the supported events for eachpossible target resource.

To learn more, see the following guides:

• Subscribe to Google Chat events
• Subscribe to Google Drive events
• Subscribe to Google Meet events

Structure of Google Workspace events

Google Workspace events follow theCloudEventsspecification, which is an industry-standard way ofdescribing event data. Google Workspaceevents contain the following:

• Attributes of the CloudEvent.
• Data about the Google Workspace resource that changed as aresult of the event

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

CloudEvent attributes

Google Workspace events contain the following requiredCloudEvents attributes:

Event data

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

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

When you create a subscription, you can specify how much resource data isincluded in the events that your app receives.

These options for event data are represented in thepayloadOptionsfield of your subscription.

Events as Google Cloud Pub/Sub messages

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

The following example shows a Google Cloud Pub/Sub message that containsan 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 includethe event type. In this case, the event is about an updated message in thespace.
• data: Theevent data with details about the updatedspaces.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/Submessages, seeGoogle Cloud Pub/Sub Protocol Binding for CloudEvents.

Related topics

• Choose Google Workspace Events API scopes
• Create a Google Workspace subscription