Edit

Use the Microsoft Graph API to get change notifications

  • Article

Namespace: microsoft.graph

The Microsoft Graph REST API uses a webhook mechanism to deliver change notifications to clients. A client is a web service that configures its own URL to receive notifications. Client apps use notifications to update their state upon changes. For more details, including how to subscribe to and handle incoming notifications, see Set up notifications for changes in user data.

An app can subscribe to changes on the Microsoft Graph resources listed in the table, which also indicates the limits that apply for subscriptions to the resources. When any limit is exceeded, attempts to create a subscription will result in an 403 Forbidden error response. The message property of the error response will explain the limit that has been exceeded.

Note

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

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 is 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.

    A known issue for the subscription 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}    		 -
    Teams callRecord Changes to all call records: /communications/callRecords Maximum subscription quotas:
  • Per organization: 100 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.

    A known issue for the subscription changeType.
    		•

    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.

    Note: Any resource path that begins with /users/{id} can also accept /me to reference the signed-in user.

    Permissions

    In general, subscription operations require read permission to the resource. For example, to get notifications for messages, your app needs the Mail.Read permission. The create subscription article lists permissions needed for each resource type. The following table lists the types of permissions your app can request to use webhooks for specific resource types.

    Permission type Supported resource types
    Delegated - work or school account alert, channel, contact, conversation, conversationMember, driveItem, event, group, list, message, team, todoTask, user
    Delegated - personal Microsoft account contact, driveItem, event, list, message, todoTask
    Application alert, callRecord, channel, chatMessage, contact, conversationMember, driveItem, event, group, list, message, printer, printTaskDefinition, team, user

    See also