Edit

Set up notifications for changes in resource data

  • Article

Change notifications enable applications to receive alerts when a Microsoft Graph resource they're interested in changes; that is, created, updated, or deleted. Microsoft Graph sends notifications to the specified client endpoint, and the client service processes the notifications according to the business requirements. For example, the service may fetch more data, update its cache and views, and so on.

Why get change notifications?

Change notifications follow an event-driven model where customers receive alerts when changes occur instead of them polling Microsoft Graph. Depending on your business logic, change notifications are suitable when:

  • You're subscribing to a resource that changes frequently.
  • You need to react to changes in near real-time.
  • You want to avoid frequently polling Microsoft Graph which might cause you to hit the throttling limits.

Types of change notifications

Microsoft Graph supports three types of change notifications:

  • Basic notifications: Change notifications that don't contain resource data other than the id of the resource that changed. When an app receives a basic notification, the service can use the id to query to changed object.
  • Rich notifications: Change notifications that include the resource data of the object that changed. For more information about rich notifications, see Rich notifications.
  • Lifecycle notifications: Notifications that alert the customer when they are at risk of missing change notifications due to the lifecycle of their subscription. For more information about lifecycle notifications, see Lifecycle notifications.

Receiving change notifications

Microsoft Graph can deliver change notifications to clients via the following channels.

Managing subscriptions

Clients can create subscriptions, renew subscriptions, and delete subscriptions. While the subscription is active and when changes occur in the subscribed resource, Microsoft Graph sends change notifications to the specified notification endpoint.

You manage the subscription using the subscription resource type and its related methods. Microsoft Graph sends change notifications in a structure defined in the changeNotificationCollection resource type.

Supported resources

An app can subscribe to changes on the Microsoft Graph resources listed in the table.

Note: Subscriptions to resources marked with an asterisk (*) are only available on the /beta endpoint.

Resource Supported resource paths Limitations
Cloud printing printer Changes when a print job is ready to be downloaded (jobFetchable event): /print/printers/{id}/jobs -
Cloud printing printTaskDefinition Changes when there's a valid job in the queue (jobStarted event): /print/printtaskdefinition/{id}/tasks -
driveItem on OneDrive (personal) Changes to content within the hierarchy of any folder: /users/{id}/drive/root -
driveItem on OneDrive for Business Changes to content within the hierarchy of the root folder: /drives/{id}/root , /users/{id}/drive/root -
group Changes to all groups: /groups

Changes to a specific group: /groups/{id}

Changes to owners of a specific group: /groups/{id}/owners

Changes to members of a specific group: /groups/{id}/members		 Maximum subscription quotas:
  • Per app (for all tenants combined): 50,000 total subscriptions.
  • Per tenant (for all applications combined): 1000 total subscriptions across all apps.
  • Per app and tenant combination: 100 total subscriptions.

    Not supported for Azure AD B2C tenants.

    NOTE: Creation and soft-deletion of groups also trigger the updated changeType.
    		•
    list under a SharePoint site Changes to content within the list: /sites/{site-id}/lists/{list-id} -
    Microsoft 365 group conversation Changes to a group's conversations: groups/{id}/conversations -
    Outlook message Changes to all messages in a user's mailbox: /users/{id}/messages , /me/messages

    Changes to messages in a user's Inbox: /users/{id}/mailFolders('inbox')/messages , /me/mailFolders('inbox')/messages    		 A maximum of 1,000 active subscriptions per mailbox for all applications is allowed.
    Outlook event Changes to all events in a user's mailbox: /users/{id}/events , /me/events A maximum of 1,000 active subscriptions per mailbox for all applications is allowed.
    Outlook personal contact Changes to all personal contacts in a user's mailbox: /users/{id}/contacts , /me/contacts A maximum of 1,000 active subscriptions per mailbox for all applications is allowed.
    Security alert Changes to a specific alert: /security/alerts/{id}

    Changes to filtered alerts: /security/alerts/?$filter={parameters}    		 For more information, see Security API alerts.
    Teams callRecord Changes to all call records: /communications/callRecords Maximum subscription quotas:
  • Per organization: 100 total subscriptions.
    		•
    Teams callRecording * Any recording becomes available in the tenant: communications/onlineMeetings/getAllRecordings

    Any recording becomes available for a specific meeting: communications/onlineMeetings/{onlineMeetingId}/recordings

    Any recording becomes available for any meeting organized by a specific user: users/{id}/onlineMeetings/getAllRecordings    		 Maximum subscription quotas:
  • Per app and online-meeting combination: 1
  • Per app and user combination: 1
  • Per user (for subscriptions tracking recordings in all onlineMeetings organized by the user): 10 subscriptions.
  • Per organization: 10,000 total subscriptions.
    		•
    Teams callTranscript All transcripts in an organization: communications/onlineMeetings/getAllTranscripts

    All transcripts for a specific meeting: communications/onlineMeetings/{onlineMeetingId}/transcripts

    Any transcript becomes available for any meeting organized by a specific user: users/{id}/onlineMeetings/getAllTranscripts*    		 Maximum subscription quotas:
  • Per app and online-meeting combination: 1
  • Per app and user combination: 1
  • Per user (for subscriptions tracking transcripts in all onlineMeetings organized by the user): 10 subscriptions.
  • Per organization: 10,000 total subscriptions.
    		•
    Teams chat Changes to any chat in the tenant: /chats

    Changes to a specific chat: /chats/{id}

    Changes to all chats in an organization where a particular Teams app is installed: /appCatalogs/teamsApps/{id}/installedToChats    		 Maximum subscription quotas:
  • Per app and chat combination: 1 subscription.
  • Per organization: 10,000 total subscriptions.
    		•
    Teams chatMessage Changes to chat messages in all channels in all teams: /teams/getAllMessages

    Changes to chat messages in a specific channel: /teams/{id}/channels/{id}/messages

    Changes to chat messages in all chats: /chats/getAllMessages

    Changes to chat messages in a specific chat: /chats/{id}/messages

    Changes to chat messages in all chats a particular user is part of: /users/{id}/chats/getAllMessages

    Changes to chat messages for all chats in an organization where a particular Teams app is installed: /appCatalogs/teamsApps/{id}/installedToChats/getAllMessages    		 Maximum subscription quotas:
  • Per app and channel or chat combination: 1 subscription.
  • Per user (for subscriptions tracking chat messages in all chats the user is part of): 10 subscriptions.
  • Per organization: 10,000 total subscriptions.
    		•
    Teams channel Changes to channels in all teams: /teams/getAllChannels

    Changes to channel in a specific team: /teams/{id}/channels    		 Maximum subscription quotas:
  • Per app and team combination: 1 subscription.
  • Per organization: 10,000 total subscriptions.
    		•
    Teams conversationMember Changes to membership in a specific team: /teams/{id}/members

    Changes to membership in all channels under a specific team: teams/{id}/channels/getAllMembers

    Changes to membership in a specific chat: /chats/{id}/members

    Changes to membership for all chats in an organization where a particular Teams app is installed: /appCatalogs/teamsApps/{id}/installedToChats/getAllMembers

    Changes to membership in all chats: /teams/getAllMembers    		 Maximum subscription quotas:
  • Per app and team combination: 1 subscription.
  • Per organization: 10,000 total subscriptions.
    		•
    Teams onlineMeeting * Changes to an online meeting: /communications/onlineMeetings/?$filter=JoinWebUrl eq {joinWebUrl}
    Teams presence Changes to a single user's presence: /communications/presences/{id}

    Changes to multiple user presences: /communications/presences?$filter=id in ({id},{id}...)
    Teams team Changes to any team in the tenant: /teams

    Changes to a specific team: /teams/{id}    		 Maximum subscription quotas:
  • Per app and team combination: 1 subscription.
  • Per organization: 10,000 total subscriptions.
    		•
    todoTask Changes to all task in a specific task list: /me/todo/lists/{todoTaskListId}/tasks -
    user Changes to all users: /users

    Changes to a specific user: /users/{id}    		 Maximum subscription quotas:
  • Per app (for all tenants combined): 50,000 total subscriptions.
  • Per tenant (for all applications combined): 1000 total subscriptions across all apps
  • Per app and tenant combination: 100 total subscriptions.

    Not supported for personal Microsoft accounts like outlook.com.

    Not supported for Azure AD B2C tenants.

    NOTE: Creation and soft-deletion of users also trigger the updated changeType.
    		•

    Note: Many resources have limits or quotas on how many subscriptions can be made against that resource. When exceeding that limit, attempts to create a subscription will result in a 403 Forbidden error response. The message property of the error response will explain the limit that has been exceeded.

    Some of these resources support rich notifications (notifications with resource data). For more information about resources that support rich notifications, see Set up change notifications that include resource data.

    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 callRecord 4,230 minutes (under 3 days)
    Teams callRecording 4,320 minutes (3 days)
    Teams callTranscript 4,320 minutes (3 days)
    Teams channel 4,320 minutes (3 days)
    Teams chat 4,320 minutes (3 days)
    Teams chatMessage 4,320 minutes (3 days)
    Teams conversationMember 4,320 minutes (3 days)
    Teams onlineMeeting 4,320 minutes (3 days)
    Teams team 4,320 minutes (3 days)
    Group conversation 4,230 minutes (under 3 days)
    OneDrive driveItem 42,300 minutes (under 30 days)
    SharePoint list 42,300 minutes (under 30 days)
    Outlook message, event, contact 4,230 minutes (under 3 days)
    user, group, other directory resources 41,760 minutes (under 29 days)
    onlineMeeting 4,230 minutes (under 3 days)
    presence 60 minutes (1 hour)
    Print printer 4,230 minutes (under 3 days)
    Print printTaskDefinition 4,230 minutes (under 3 days)
    todoTask 4,230 minutes (under 3 days)

    Webhooks for this resource are only available in the global endpoint and not in the national clouds.
    baseTask (deprecated) 4,230 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.

    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
    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 Less than 2 minutes 15 minutes
    list Less than 1 minute 5 minutes
    message Less than 1 minute 3 minutes
    onlineMeeting Less than 10 seconds 1 minute
    presence Less than 10 seconds 1 minute
    printer Less than 1 minute 5 minutes
    printTaskDefinition Less than 1 minute 5 minutes
    team Less than 10 seconds 60 minutes
    todoTask Less than 2 minutes 15 minutes
    user Less than 2 minutes 15 minutes

    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.

    Code samples

    The following code samples are available on GitHub.

    Deployment resources

    See also