Subscribe to Google Drive events

This page describes the Google Drive events that your app can subscribe to using the Google Workspace Events API. After you decide which types of events you need, create a subscription to start receiving events from Drive.

To learn more about developing apps for Drive, see the Google Drive API overview.

Supported Drive events

Google Workspace subscriptions let you receive events about the following types of changes in Drive:

• A file is:
  • Added to a folder or shared drive.
  • Moved to a folder or shared drive.
  • Edited or a new revision is uploaded.
  • Trashed or removed from the trash.
• An access proposal is created or resolved on a file.

Resources that you can monitor for events

To receive events, you specify a Drive resource to monitor, which is called the target resource of the subscription.

The Google Workspace Events API supports the following target resources for Drive:

Event types for creating subscriptions

When you create a subscription to a Drive resource, you use the eventTypes[] field to specify which types of events you want to receive. Event types are formatted according to the CloudEvents specification, such as google.workspace.APPLICATION.RESOURCE.VERSION.ACTION.

For example, to receive events about a file being created in a folder or shared drive, you specify the file as the target resource, and the event type as google.workspace.drive.file.v3.created. To receive events about an access proposal being created on a file, you specify the access proposal as the target resource, and the event type as google.workspace.drive.accessproposal.v3.created. To learn more about how events work, see Structure of Google Workspace events.

The following table displays which event types are supported for subscriptions to Drive resources:

Event data

This section describes event data and example payloads for events in Drive.

When your Google Workspace subscription receives an event from Drive, the data field contains the payload for the event. This payload has information about the Google Workspace resource that changed. For example, if you've subscribed to file events, the payload for these events contains information about the file resource that changed.

Resource data in the event payload

When you create a subscription, you can specify whether you want the payload to include details about the resource, or just the name of the resource. For example, if you want to receive events about files in Drive, you can specify which fields of a files resource you want to receive in the event payload.

The following table provides examples of JSON payloads for a subscription to the Drive resource. The file ID contains letters, numbers, and some special characters structured as files/^[01][0-9a-zA-Z_-]+$/. For example, files/1aaabbbAAABBB111222-_. For each event that the subscription receives, the payload appears in the data field of the event:

{
  "fileCreatedEvent": {
    "file": {
      "id": "FILE_ID",
      "parent": "PARENT_ID",
      "version": "63",
      "mimeType": "application/vnd.google-apps.document"
    }
  }
}
      

{
  "fileCreatedEvent": {
    "file": {
      "id": "FILE_ID"
    }
  }
}
      

{
  "fileMovedEvent": {
    "file": {
      "id": "FILE_ID",
      "parent": "PARENT_ID",
      "version": "63",
      "mimeType": "application/vnd.google-apps.document"
    }
  }
}
      

{
  "fileMovedEvent": {
    "file": {
      "id": "FILE_ID"
    }
  }
}
      

{
  "fileContentChangedEvent": {
    "file": {
      "id": "FILE_ID",
      "parent": "PARENT_ID",
      "version": "63",
      "mimeType": "application/vnd.google-apps.document"
    }
  }
}
      

{
  "fileContentChangedEvent": {
    "file": {
      "id": "FILE_ID"
    }
  }
}
      

{
  "fileDeletedEvent": {
    "file": {
      "id": "FILE_ID",
      "parent": "PARENT_ID",
      "version": "63",
      "mimeType": "application/vnd.google-apps.document"
    }
  }
}
      

{
  "fileDeletedEvent": {
    "file": {
      "id": "FILE_ID"
    }
  }
}
      

{
  "fileTrashedEvent": {
    "file": {
      "id": "FILE_ID",
      "parent": "PARENT_ID",
      "version": "63",
      "mimeType": "application/vnd.google-apps.document"
    }
  }
}
      

{
  "fileTrashedEvent": {
    "file": {
      "id": "FILE_ID"
    }
  }
}
      

{
  "fileUntrashedEvent": {
    "file": {
      "id": "FILE_ID",
      "parent": "PARENT_ID",
      "version": "63",
      "mimeType": "application/vnd.google-apps.document"
    }
  }
}
      

{
  "fileUntrashedEvent": {
    "file": {
      "id": "FILE_ID"
    }
  }
}
      

{
  "accessProposalCreatedEvent": {
    "accessProposal": [
      {
        "file_id": "FILE_ID",
        "proposalId": "PROPOSAL_ID",
        "recipientEmailAddress": "63",
        "requesterEmailAddress": "application/vnd.google-apps.document",
        "requestMessage": "grant me access to this file",
        "rolesAndViews": [
          {
            "role": "writer",
            "view": "published"
          }
        ]
      }
    ]
  }
}
      

{
  "accessProposalCreatedEvent": {
    "accessProposal": [
      {
        "proposalId": "PROPOSAL_ID"
      }
    ]
  }
}
      

{
  "accessProposalResolvedEvent": {
    "accessProposal": [
      {
        "file_id": "FILE_ID",
        "proposalId": "PROPOSAL_ID",
        "recipientEmailAddress": "63",
        "requesterEmailAddress": "application/vnd.google-apps.document",
        "requestMessage": "resolve access to this file",
        "rolesAndViews": [
          {
            "role": "writer",
            "view": "published"
          }
        ]
      }
    ]
  }
}
      

{
  "accessProposalResolvedEvent": {
    "accessProposal": [
      {
        "proposalId": "PROPOSAL_ID"
      }
    ]
  }
}
      

• When the includeDescendants boolean field in DriveOptions is true, Drive subscriptions on shared drives and folders always dispatch an event, even if the file that triggered the event is nested many layers below the folder used for the Drive subscription.
• Even though you may have created a subscription on a folder, you may not receive all events within the file hierarchy as the user or application may not be granted access to them. In this case, the subscription remains active but you won't receive any events for resources you don't have access to.
• Subscriptions are supported for events on all files and folders but not on the root folder of shared drives. Subscriptions are only supported for files and folders inside shared drives. Changes made directly to the root folder of a shared drives won't trigger events.
• The user that authorizes the subscription must have permission on the file corresponding to the events that they subscribe to.
• The subscription only receives events for resources where the user has access through their Google Workspace account or Google Account.

Related topics

• Google Workspace Events API overview
• Structure of Google Workspace events
• Choose Google Workspace Events API scopes
• Choose Google Drive API scopes