subscription resource type

A subscription allows a client app to receive notifications about data on the Microsoft Graph. Currently subscriptions are enabled for the following datasets:

  1. Mail, events, and contacts from Outlook
  2. Conversations from Office Groups.
  3. Drive root items from OneDrive

JSON representation

Here is a JSON representation of the resource.

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


Property Type Description
changeType string 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. Drive root Item notifications require the use of updated only.
notificationUrl string The URL of the endpoint that will receive the notifications. This URL has to make use of the HTTPS protocol.
resource string Specifies the resource that will be monitored for changes. Do not include the base URL ({version}/).
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 values.
clientState string Specifies the value of the clientState property sent by the service in each notification. The maximum length is 255 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.

Maximum Expiration Times Per Resource

Resource Maximum Expiration Time
Mail 4230 minutes.
Calendar 4230 minutes.
Contacts 4230 minutes.
Group conversations 4230 minutes.
Drive root items 86400 minutes.




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