Use the Microsoft Graph API to get change notifications

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.

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.

Using the Microsoft Graph API, an app can subscribe to changes on the following resources:

Resource Supported resource paths Resource data can be included in notifications
Cloud printing printer Changes when a print job is ready to be downloaded (JobFetchable event):
/print/printers/{id}/jobs
No
Cloud printing printTaskDefinition Changes when there is a valid job in the queue (JobStarted event) :
/print/printtaskdefinition/{id}/tasks
No
driveItem on OneDrive for Business Changes to content within the hierarchy of the root folder:
/drives/{id}/root
/users/{id}/drive/root
No
driveItem on OneDrive (personal) Changes to content within the hierarchy of any folder:
/users/{id}/drive/root
No
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
No
list under a SharePoint site /sites/{id}/lists/{id} No
Microsoft 365 group conversation Changes to a group's conversations:
groups/{id}/conversations
No
Outlook event Changes to all events in a user's mailbox:
/users/{id}/events
Yes
Outlook message Changes to all messages in a user's mailbox:
/users/{id}/messages
Changes to messages in a user's Inbox:
/users/{id}/mailFolders('inbox')/messages
Yes
Outlook personal contact Changes to all personal contacts in a user's mailbox:
/users/{id}/contacts
Yes
Security alert Changes to a specific alert:
/security/alerts/{id}
Changes to filtered alerts:
/security/alerts/?$filter
No
Teams callRecord Changes to all call records: /communications/callRecords No
Teams channel Changes to channels in all teams:
/teams/getAllChannels
Changes to channel in a specific team:
/teams/{id}/channels
Yes
Teams chat Changes to any chat in the tenant:
/chats
Changes to a specific chat:
/chats/{id}
Yes
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
Yes
Teams conversationMember Changes to membership in a specific team:
/teams/{id}/members
Changes to membership in a specific chat:
/chats/{id}/members
Changes to membership in all chats:
/chats/getAllMembers
Changes to membership in all channels under a specific team:
teams/{id}/channels/getAllMembers
Yes
Teams onlineMeeting Changes to an online meeting:
/communications/onlinemeeting/{meeting-id}
Yes
Teams presence Changes to a single user's presence: /communications/presences/{id}
Changes to multiple user presences:
/communications/presences?$filter=id in ({id},{id}...)
Yes
Teams team Changes to any team in the tenant:
/teams
Changes to a specific team:
/teams/{id}
Yes
baseTask Changes to all task in a specific task list:
/me/tasks/lists/{baseTaskListId}/tasks
Changes to all tasks:
/me/tasks/lists/alltasks
No
user Changes to all users:
/users
Changes to a specific user:
/users/{id}
No

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, chat, contact, conversation, conversationMember, driveItem, list, event, group, message, user, presence, chatMessage (preview), team, baseTask
Delegated - personal Microsoft account contact, driveItem, list, event, message, baseTask
Application alert, channel, chat, contact, driveItem, list, event, group, message, user, callRecord, chatMessage, conversationMember, onlinemeeting, printer, printTaskDefinition, team

See also