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.
Caution
Existing apps that use this feature with baseTask or baseTaskList should be updated, as the to-do API set built on these resources is deprecated as of May 31, 2022. That API set will stop returning data on August 31, 2022. Please use the API set built on todoTask.
Represents a subscription that allows a client app to receive change notifications about changes to data in Microsoft Graph.
For more information about subscriptions and change notifications, including resources that support change notifications, see Set up notifications for changes in resource data.
Methods
| Method | Return Type | Description |
|---|---|---|
| List | subscription | List active subscriptions. |
| Create | subscription | Subscribe a listener application to receive change notifications when Microsoft Graph data changes. |
| Get | subscription | Read properties and relationships of subscription object. |
| Update | subscription | Renew a subscription by updating its expiration time. |
| Delete | None | Delete a subscription object. |
| Reauthorize | None | Reauthorize a subscription when you receive a reauthorizationRequired challenge. |
Properties
| Property | Type | Description |
|---|---|---|
| applicationId | String | Optional. Identifier of the application used to create the subscription. Read-only. |
| changeType | String | Required. Indicates the type of change in the subscribed resource that raises a change notification. The supported values are: created, updated, deleted. Multiple values can be combined using a comma-separated list. Note: updated changeType. updated and deleted changeType. Use updated to receive notifications when user or group is created, updated, or soft deleted. Use deleted to receive notifications when user or group is permanently deleted. |
| clientState | String | Optional. 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. |
| creatorId | String | Optional. 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. |
| encryptionCertificate | String | Optional. A base64-encoded representation of a certificate with a public key used to encrypt resource data in change notifications. Optional but required when includeResourceData is true. |
| encryptionCertificateId | String | Optional. A custom app-provided identifier to help identify the certificate needed to decrypt resource data. Required when includeResourceData is true. |
| expirationDateTime | DateTimeOffset | 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. For the maximum supported subscription length of time, see Subscription lifetime. |
| id | String | Optional. Unique identifier for the subscription. Read-only. |
| includeResourceData | Boolean | Optional. When set to true, change notifications include resource data (such as content of a chat message). |
| latestSupportedTlsVersion | String | Optional. 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. |
| lifecycleNotificationUrl | String | Required for Teams resources if the expirationDateTime value is more than 1 hour from now; optional otherwise. The URL of the endpoint that receives lifecycle notifications, including subscriptionRemoved, reauthorizationRequired, and missed notifications. This URL must make use of the HTTPS protocol. For more information, see Reduce missing subscriptions and change notifications. |
| notificationContentType | String | Optional. Desired content-type for Microsoft Graph change notifications for supported resource types. The default content-type is application/json. |
| notificationQueryOptions | String | Optional. OData query options for specifying the value for the targeting resource. Clients receive notifications when the 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 deliver notifications whenever a resource reaches the desired state mentioned in the notificationQueryOptions property. For example, when the print job is completed or when a print job resource isFetchable property value becomes true etc. Supported only for Universal Print Service. For more information, see Subscribe to change notifications from cloud printing APIs using Microsoft Graph. |
| notificationUrl | String | Required. The URL of the endpoint that receives the change notifications. This URL must make use of the HTTPS protocol. Any query string parameter included in the notificationUrl property is included in the HTTP POST request when Microsoft Graph sends the change notifications. |
| notificationUrlAppId | String | Optional. The app ID that the subscription service can use to generate the validation token. The value allows the client to validate the authenticity of the notification received. |
| resource | String | Required. Specifies the resource that is monitored for changes. Don't include the base URL (https://graph.microsoft.com/beta/). See the possible resource path values for each supported resource. |
Subscription lifetime
Subscriptions have a limited lifetime. Apps need to renew their subscriptions before the expiration time; otherwise, they need to create a new subscription. Apps can also unsubscribe at any time to stop getting change notifications.
The following table shows the maximum expiration times for subscriptions per resource in Microsoft Graph.
| Resource | Maximum expiration time |
|---|---|
| Security alert | 43,200 minutes (under 30 days) |
| Teams approvals | 43,200 minutes (under 30 days) |
| Teams callRecord | 4,230 minutes (under three days) |
| Teams callRecording | 4,320 minutes (three days) |
| Teams callTranscript | 4,320 minutes (three days) |
| Teams channel | 4,320 minutes (three days) |
| Teams chat | 4,320 minutes (three days) |
| Teams chatMessage | 4,320 minutes (three days) |
| Teams conversationMember | 4,320 minutes (three days) |
| Teams onlineMeeting | 4,320 minutes (three days) |
| Teams team | 4,320 minutes (three days) |
| Teams teamsAppInstallation | 4,320 minutes (3 days) |
| Teams Shifts offerShiftRequest | 360 minutes (6 hours) |
| Teams Shifts openShiftChangeRequest | 360 minutes (6 hours) |
| Teams Shifts shift | 360 minutes (6 hours) |
| Teams Shifts swapShiftsChangeRequest | 360 minutes (6 hours) |
| Teams Shifts timeOffRequest | 360 minutes (6 hours) |
| Group conversation | 4,230 minutes (under three days) |
| OneDrive driveItem | 42,300 minutes (under 30 days) |
| SharePoint list | 42,300 minutes (under 30 days) |
| Outlook message, event, contact | 10,080 minutes (under seven days) |
| user, group, other directory resources | 41,760 minutes (under 29 days) |
| onlineMeeting | 4,230 minutes (under three days) |
| presence | 60 minutes (1 hour) |
| Print printer | 4,230 minutes (under three days) |
| Print printTaskDefinition | 4,230 minutes (under three days) |
| todoTask | 4,230 minutes (under three days) Webhooks for this resource are only available in the global endpoint and not in the national clouds. |
| baseTask (deprecated) | 4,230 minutes (under three 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.
Latency
The following table lists the latency to expect between an event happening in the service and the delivery of the change notification.
| Resource | Average latency | Maximum latency |
|---|---|---|
| alert 1 | Less than 3 minutes | 5 minutes |
| approvals | Less than 10 seconds | 40 seconds |
| calendar | Less than 1 minute | 3 minutes |
| callRecord | Less than 15 minutes | 60 minutes |
| callRecording | Less than 10 seconds | 60 minutes |
| callTranscript | Less than 10 seconds | 60 minutes |
| channel | Less than 10 seconds | 60 minutes |
| chat | Less than 10 seconds | 60 minutes |
| chatMessage | Less than 10 seconds | 1 minute |
| contact | Less than 1 minute | 3 minutes |
| conversation | Unknown | Unknown |
| conversationMember | Less than 10 seconds | 60 minutes |
| driveItem | Less than 1 minute | 5 minutes |
| event | Unknown | Unknown |
| group | Unknown | Unknown |
| list | Less than 1 minute | 5 minutes |
| message | Less than 1 minute | 3 minutes |
| offerShiftRequest | Less than 1 minute | 60 minutes |
| onlineMeeting | Less than 10 seconds | 1 minute |
| openShiftChangeRequest | Less than 1 minute | 60 minutes |
| presence | Less than 10 seconds | 1 minute |
| printer | Less than 1 minute | 5 minutes |
| printTaskDefinition | Less than 1 minute | 5 minutes |
| shift | Less than 1 minute | 60 minutes |
| swapShiftsChangeRequest | Less than 1 minute | 60 minutes |
| team | Less than 10 seconds | 60 minutes |
| teamsAppInstallation | Less than 10 seconds | 60 minutes |
| timeOffRequest | Less than 1 minute | 60 minutes |
| todoTask | Less than 2 minutes | 15 minutes |
| user | Unknown | Unknown |
1 The latency provided for the alert resource is only applicable after the alert is created. It doesn't include the time it takes for a rule to create an alert from the data.
Relationships
None.
JSON representation
The following JSON representation shows the resource type.
{
"@odata.type": "#microsoft.graph.subscription",
"applicationId": "String",
"changeType": "String",
"clientState": "String",
"creatorId": "String",
"encryptionCertificate": "String",
"encryptionCertificateId": "String",
"expirationDateTime": "String (timestamp)",
"id": "String (identifier)",
"includeResourceData": "Boolean",
"latestSupportedTlsVersion": "String",
"lifecycleNotificationUrl": "String",
"notificationContentType": "String",
"notificationQueryOptions": "String",
"notificationUrl": "String",
"notificationUrlAppId": "String",
"resource": "String"
}