subscription resource type

A subscription allows a client app to receive notifications about changes to data in Microsoft Graph. Currently, subscriptions are enabled for the following resources:

  • A message, event, or contact in Outlook
  • A conversation of an Office 365 group
  • Content in the hierarchy of a root folder driveItem in OneDrive for Business, or of a root folder or subfolder driveItem in a user's personal OneDrive
  • A user or group in Azure Active Directory
  • An alert from the Microsoft Graph Security API

JSON representation

Here is a JSON representation of the resource.

  "changeType": "string",
  "notificationUrl": "string",
  "resource": "string",
  "applicationId" : "string",
  "expirationDateTime": "String (timestamp)",
  "id": "string (identifier)",
  "clientState": "string",
  "creatorId": "string"


Property Type Description
changeType string Required. Indicates the type of change in the subscribed resource that will raise a notification. The supported values are: created, updated, deleted. Multiple values can be combined using a comma-separated list.

Note: Drive root item notifications support only the updated changeType. User and group notifications support updated and deleted changeType.
notificationUrl string Required. The URL of the endpoint that will receive the notifications. This URL must make use of the HTTPS protocol.
resource string Required. Specifies the resource that will be monitored for changes. Do not include the base URL (
expirationDateTime dateTime Required. Specifies the date and time when the webhook subscription expires. The time is in UTC, and can be an amount of time from subscription creation that varies for the resource subscribed to. See the table below for maximum supported subscription length of time.
clientState string Optional. Specifies the value of the clientState property sent by the service in each notification. The maximum length is 128 characters. The client can check that the notification came from the service by comparing the value of the clientState property sent with the subscription with the value of the clientState property received with each notification.
id string Unique identifier for the subscription. Read-only.
applicationId string Identifier of the application used to create the subscription. Read-only.
creatorId string Identifier of the user or service principal that created the subscription. If the app used delegated permissions to create the subscription, this field contains the id of the signed-in user the app called on behalf of. If the app used application permissions, this field contains the id of the service principal corresponding to the app. Read-only.

Maximum length of subscription per resource type

Resource Maximum Expiration Time
User, group, other directory resources 4230 minutes (under 3 days)
Mail 4230 minutes (under 3 days)
Calendar 4230 minutes (under 3 days)
Contacts 4230 minutes (under 3 days)
Group conversations 4230 minutes (under 3 days)
Drive root items 4230 minutes (under 3 days)
Security alerts 43200 minutes (under 30 days)

Note: Existing applications and new applications should not exceed the supported value. In the future, any requests to create or renew a subscription beyond the maximum value will fail.




Method Return Type Description
Create subscription subscription Subscribes a listener application to receive notifications when Microsoft Graph data changes.
Update subscription subscription Renews a subscription by updating its expiration time.
List subscriptions subscription Lists active subscriptions.
Get subscription subscription Reads properties and relationships of subscription object.
Delete subscription None Deletes a subscription object.