--- title: "PATCH /v1/{+name}" method: PATCH path: "/v1/{+name}" tags: ["subscriptions"] --- # PATCH /v1/{+name} `PATCH /v1/{+name}` Updates or renews a Google Workspace subscription. To learn how to use this method, see [Update or renew a Google Workspace subscription](https://developers.google.com/workspace/events/guides/update-subscription). For a subscription on a [Chat target resource](https://developers.google.com/workspace/events/guides/events-chat), you can update a subscription as: - A Chat app by specifying an authorization scope that begins with `chat.app` and getting one-time administrator approval. To learn more, see [Authorize as a Chat app with administrator approval](https://developers.google.com/workspace/chat/authenticate-authorize-chat-app). - A user by specifying an authorization scope that doesn't include `app` in its name. To learn more, see [Authorize as a Chat user](https://developers.google.com/workspace/chat/authenticate-authorize-chat-user). ## Path parameters - `name` string, required ## Query parameters - `updateMask` string - `validateOnly` boolean ## Request body - Subscription — A subscription to receive events about a Google Workspace resource. To learn more about subscriptions, see the [Google Workspace Events API overview](https://developers.google.com/workspace/events). - `uid` string — Output only. System-assigned unique identifier for the subscription. - `updateTime` string, google-datetime — Output only. The last time that the subscription is updated. - `state` 'STATE_UNSPECIFIED' | 'ACTIVE' | 'SUSPENDED' | 'DELETED' — Output only. The state of the subscription. Determines whether the subscription can receive events and deliver them to the notification endpoint. - `ttl` string, google-duration — Input only. The time-to-live (TTL) or duration for the subscription. If unspecified or set to `0`, uses the maximum possible duration. - `driveOptions` DriveOptions — Additional supported options for serving Drive events. - `includeDescendants` boolean — Optional. Immutable. For subscriptions to Google Drive events, whether to receive events about Drive files that are children of the target folder or shared drive. * If `false`, the subscription only receives events about changes to the folder or shared drive that's specified as the `targetResource`. * If `true`, the `mimeType` field of the `file` resource must be set to `application/vnd.google-apps.folder`. For details, see [Google Drive event types](https://developers.google.com/workspace/events/guides/events-drive#event-types). - `targetResource` string — Required. Immutable. The Google Workspace resource that's monitored for events, formatted as the [full resource name](https://google.aip.dev/122#full-resource-names). To learn about target resources and the events that they support, see [Supported Google Workspace events](https://developers.google.com/workspace/events#supported-events). A user can only authorize your app to create one subscription for a given target resource. If your app tries to create another subscription with the same user credentials, the request returns an `ALREADY_EXISTS` error. - `name` string — Identifier. Resource name of the subscription. Format: `subscriptions/{subscription}` - `notificationEndpoint` NotificationEndpoint — The endpoint where the subscription delivers events. - `pubsubTopic` string — Immutable. The Pub/Sub topic that receives events for the subscription. Format: `projects/{project}/topics/{topic}` You must create the topic in the same Google Cloud project where you create this subscription. Note: The Google Workspace Events API uses [ordering keys](https://cloud.google.com/pubsub/docs/ordering) for the benefit of sequential events. If the Cloud Pub/Sub topic has a [message storage policy](https://cloud.google.com/pubsub/docs/resource-location-restriction#exceptions) configured to exclude the nearest Google Cloud region, publishing events with ordering keys will fail. When the topic receives events, the events are encoded as Pub/Sub messages. For details, see the [Google Cloud Pub/Sub Protocol Binding for CloudEvents](https://github.com/googleapis/google-cloudevents/blob/main/docs/spec/pubsub.md). - `eventTypes` string[] — Required. Unordered list. Input for creating a subscription. Otherwise, output only. One or more types of events to receive about the target resource. Formatted according to the CloudEvents specification. The supported event types depend on the target resource of your subscription. For details, see [Supported Google Workspace events](https://developers.google.com/workspace/events/guides#supported-events). By default, you also receive events about the [lifecycle of your subscription](https://developers.google.com/workspace/events/guides/events-lifecycle). You don't need to specify lifecycle events for this field. If you specify an event type that doesn't exist for the target resource, the request returns an HTTP `400 Bad Request` status code. - `etag` string — Optional. This checksum is computed by the server based on the value of other fields, and might be sent on update requests to ensure the client has an up-to-date value before proceeding. - `userAuthority` string — Output only. The user who authorized the creation of the subscription. The user must be able to view the `target_resource`. For Google Workspace users, the `{user}` value is the [`user.id`](https://developers.google.com/workspace/admin/directory/reference/rest/v1/users#User.FIELDS.id) field from the Directory API. Format: `users/{user}` - `createTime` string, google-datetime — Output only. The time when the subscription is created. - `expireTime` string, google-datetime — Non-empty default. The timestamp in UTC when the subscription expires. Always displayed on output, regardless of what was used on input. - `authority` string — Output only. The user who authorized the creation of the subscription. When a user authorizes the subscription, this field and the `user_authority` field have the same value and the format is: Format: `users/{user}` For Google Workspace users, the `{user}` value is the [`user.id`](https://developers.google.com/admin-sdk/directory/reference/rest/v1/users#User.FIELDS.ids) field from the Directory API. When a Chat app authorizes the subscription, only `service_account_authority` field populates and this field is empty. - `serviceAccountAuthority` string — Output only. The service account that was used to authorize the creation of the subscription. This service account must be owned by the same Google Cloud project where you created this subscription. Format: `projects/{project_id}/serviceAccounts/{service_account_id}` - `payloadOptions` PayloadOptions — Options about what data to include in the event payload. Only supported for Google Chat and Google Drive events. - `includeResource` boolean — Optional. Whether the event payload includes data about the resource that changed. For example, for an event where a Google Chat message was created, whether the payload contains data about the [`Message`](https://developers.google.com/chat/api/reference/rest/v1/spaces.messages) resource. If false, the event payload only includes the name of the changed resource. - `fieldMask` string, google-fieldmask — Optional. If `include_resource` is set to `true`, the list of fields to include in the event payload. Separate fields with a comma. For example, to include a Google Chat message's sender and create time, enter `message.sender,message.createTime`. If omitted, the payload includes all fields for the resource. If you specify a field that doesn't exist for the resource, the system ignores the field. - `reconciling` boolean — Output only. If `true`, the subscription is in the process of being updated. - `suspensionReason` 'ERROR_TYPE_UNSPECIFIED' | 'USER_SCOPE_REVOKED' | 'APP_SCOPE_REVOKED' | 'RESOURCE_DELETED' | 'USER_AUTHORIZATION_FAILURE' | 'APP_AUTHORIZATION_FAILURE' | 'ENDPOINT_PERMISSION_DENIED' | 'ENDPOINT_NOT_FOUND' | 'ENDPOINT_RESOURCE_EXHAUSTED' | 'OTHER' — Output only. The error that suspended the subscription. To reactivate the subscription, resolve the error and call the `ReactivateSubscription` method. ## Response `200` Successful response --- [API](https://skmtc.dev/google/apis/workspaceevents.md) · [All operations](https://skmtc.dev/google/apis/workspaceevents/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/google/workspaceevents/revisions/d6202517e9f3/schema)