subscription resource type

Namespace: microsoft.graph

Important

APIs under the /beta version in Microsoft Graph are subject to change. Use of these APIs in production applications is not supported. To determine whether an API is available in v1.0, use the Version selector.

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

See Use the Microsoft Graph API to get change notifications for the possible resource path values for each supported resource.

Methods

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

Properties

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

Note: Drive root item and list change notifications support only the updated changeType. User and group change notifications support updated and deleted changeType.
All
notificationUrl string The URL of the endpoint that receives the change notifications. This URL must make use of the HTTPS protocol. Required. All
lifecycleNotificationUrl string The URL of the endpoint that receives lifecycle notifications, including subscriptionRemoved and missed notifications. This URL must make use of the HTTPS protocol. Optional.

Read more about how Outlook resources use lifecycle notifications.
All
resource string Specifies the resource that will be monitored for changes. Do not include the base URL (https://graph.microsoft.com/beta/). See the possible resource path values for each supported resource. Required. All
expirationDateTime DateTimeOffset 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. Required. All
clientState string Specifies the value of the clientState property sent by the service in each change notification. The maximum length is 255 characters. The client can check that the change 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 change notification. Optional. All
id string Unique identifier for the subscription. Read-only. All
applicationId string Identifier of the application used to create the subscription. Read-only. All
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. All
includeResourceData Boolean When set to true, change notifications include resource data (such as content of a chat message). Optional. All
encryptionCertificate string A base64-encoded representation of a certificate with a public key used to encrypt resource data in change notifications. Optional. Required when includeResourceData is true. All
encryptionCertificateId string A custom app-provided identifier to help identify the certificate needed to decrypt resource data. Optional. Required when includeResourceData is true. All
latestSupportedTlsVersion string Specifies the latest version of Transport Layer Security (TLS) that the notification endpoint, specified by notificationUrl, supports. The possible values are: v1_0, v1_1, v1_2, v1_3.
For subscribers whose notification endpoint supports a version lower than the currently recommended version (TLS 1.2), specifying this property by a set timeline allows them to temporarily use their deprecated version of TLS before completing their upgrade to TLS 1.2. For these subscribers, not setting this property per the timeline would result in subscription operations failing.

For subscribers whose notification endpoint already supports TLS 1.2, setting this property is optional. In such cases, Microsoft Graph defaults the property to v1_2.
All
notificationContentType string Desired content-type for MS Graph change notifications for supported resource types. The default content-type is the "application/json" content-type. All
notificationQueryOptions string OData Query Options for specifying value for the targeting resource. Clients receive notifications when resource reaches the state matching the query options provided here. With this new property in the subscription creation payload along with all existing properties, Webhooks will deliver notifications whenever a resource reaches the desired state mentioned in the notificationQueryOptions property eg when the print job is completed, when a print job resource isFetchable property value becomes true etc. Universal Print Service

Maximum length of subscription per resource type

Resource Maximum expiration time
Security alert 43200 minutes (under 30 days)
Teams callRecord 4230 minutes (under 3 days)
Teams channel 60 minutes (1 hour)
Teams chatMessage 60 minutes (1 hour)
Teams conversationMember 60 minutes (1 hour)
Teams team 60 minutes (1 hour)
Group conversation 4230 minutes (under 3 days)
OneDrive driveItem 42300 minutes (under 30 days)
SharePoint list 42300 minutes (under 30 days)
Outlook message, event, contact 4230 minutes (under 3 days)
user, group, other directory resources 41760 minutes (under 29 days)
presence 60 minutes (1 hour)
Print printer 4230 minutes (under 3 days)
Print printTaskDefinition 4230 minutes (under 3 days)
todoTask 4230 minutes (under 3 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.

Relationships

None.

JSON representation

Here is a JSON representation of the resource.

{
  "changeType": "string",
  "notificationUrl": "string",
  "lifecycleNotificationUrl": "string",
  "resource": "string",
  "applicationId" : "string",
  "expirationDateTime": "string (timestamp)",
  "id": "string (identifier)",
  "clientState": "string",
  "creatorId": "string",
  "includeResourceData": "boolean",
  "encryptionCertificate": "string",
  "encryptionCertificateId": "string",
  "latestSupportedTlsVersion": "string",
  "notificationContentType": "string",
  "notificationQueryOptions": "string"
}