Subscribe to events published by Microsoft Graph API

This article describes steps to subscribe to events published by Microsoft Graph API. The following table lists the resources for which events are available through Graph API. For every resource, events for create, update and delete state changes are supported.

Microsoft event source Resource(s) Available event types
Azure Active Directory User, Group Azure AD event types
Microsoft Outlook Event (calendar meeting), Message (email), Contact Microsoft Outlook event types
Microsoft Teams ChatMessage, CallRecord (meeting) Microsoft Teams event types
Microsoft SharePoint and OneDrive DriveItem
Microsoft SharePoint List
Security alerts Alert
Microsoft Conversations Conversation

Important

If you aren't familiar with the Partner Events feature, see Partner Events overview.

Why you should use Microsoft Graph API with Event Grid as a destination?

Besides the ability to subscribe to Microsoft Graph API events via Event Grid, you have other options through which you can receive similar notifications (not events). Consider using Microsoft Graph API to deliver events to Event Grid if you have at least one of the following requirements:

  • You're developing an event-driven solution that requires events from Azure Active Directory, Outlook, Teams, etc. to react to resource changes. You require the robust eventing model and publish-subscribe capabilities that Event Grid provides. For an overview of Event Grid, see Event Grid concepts.
  • You want to use Event Grid to route events to multiple destinations using a single Graph API subscription and you want to avoid managing multiple Graph API subscriptions.
  • You require to route events to different downstream applications, webhooks or Azure services depending on some of the properties in the event. For example, you may want to route event types such as Microsoft.Graph.UserCreated and Microsoft.Graph.UserDeleted to a specialized application that processes users' onboarding and off-boarding. You may also want to send Microsoft.Graph.UserUpdated events to another application that syncs contacts information, for example. You can achieve that using a single Graph API subscription when using Event Grid as a notification destination. For more information, see event filtering and event handlers.
  • Interoperability is important to you. You want to forward and handle events in a standard way using CNCF's CloudEvents specification standard, to which Event Grid fully complies.
  • You like the extensibility support that CloudEvents provides. For example, if you want to trace events across compliant systems, you may use CloudEvents extension Distributed Tracing. Learn more about more CloudEvents extensions.
  • You want to use proven event-driven approaches adopted by the industry.

High-level steps

The common steps to subscribe to events published by any partner, including Graph API, are described in subscribe to partner events. For a quick reference, the steps described in that article are listed here. This article deals with step 3: enable events flow to a partner topic.

  1. Register the Event Grid resource provider with your Azure subscription.
  2. Authorize partner to create a partner topic in your resource group.
  3. Enable events to flow to a partner topic
  4. Activate partner topic so that your events start flowing to your partner topic.
  5. Subscribe to events.

Enable Microsoft Graph API events to flow to your partner topic

Important

Microsoft Graph API's (MGA) ability to send events to Event Grid (a generally available service) is in private preview. In the following steps, you will follow instructions from Node.js, Java, and.NET Core Webhook samples to enable flow of events from Microsoft Graph API. At some point in the sample, you will have an application registered with Azure AD. Email your application ID to mailto:ask.graph.and.grid@service.microsoft.com?subject=Please allow my Azure AD application with ID to send events through Graph API so that the Microsoft Graph API team can add your application ID to allow list to use this new capability.

You request Microsoft Graph API to send events by creating a Graph API subscription. When you create a Graph API subscription, the http request should look like the following sample:

POST to https://canary.graph.microsoft.com/testprodbetawebhooks1/subscriptions

Body:
{
    "changeType": "Updated,Deleted,Created",
    "notificationUrl": "EventGrid:?azuresubscriptionid=8A8A8A8A-4B4B-4C4C-4D4D-12E12E12E12E&resourcegroup=yourResourceGroup&partnertopic=youPartnerTopic&location=theAzureRegionFortheTopic",
    "resource": "users",
    "expirationDateTime": "2022-04-30T00:00:00Z",
    "clientState": "mysecret"
}

Here are some of the key payload properties:

  • changeType: the kind of resource changes for which you want to receive events. Valid values: Updated, Deleted, and Created. You can specify one or more of these values separated by commas.
  • notificationUrl: a URI that conforms to the following pattern: EventGrid:?azuresubscriptionid=<you-azure-subscription-id>&resourcegroup=<your-resource-group-name>&partnertopic=<the-name-for-your-partner-topic>&location=<the-Azure-region-where-you-want-the-topic-created>.
  • resource: the resource for which you need events announcing state changes.
  • expirationDateTime: the expiration time at which the subscription will expire and hence the flow of events will stop. It must conform to the format specified in RFC 3339. You must specify an expiration time that is within the maximum subscription length allowable for the resource type used.
  • client state. A value that is set by you when creating a Graph API subscription. For more information, see Graph API subscription properties.

Note

Microsoft Graph API's capability to send events to Event Grid is only available in a specific Graph API environment. You will need to update your code so that it uses the following Graph API endpoint https://canary.graph.microsoft.com/testprodbetawebhooks1. For example, this is the way you can set the endpoint on your graph client (com.microsoft.graph.requests.GraphServiceClient) using the Graph API Java SDK:

graphClient.setServiceRoot("https://canary.graph.microsoft.com/testprodbetawebhooks1");

You can create a Microsoft Graph API subscription by following the instructions in the Microsoft Graph API webhook samples that include code samples for NodeJS, Java (Spring Boot), and .NET Core. There are no samples available for Python, Go and other languages yet, but the Graph SDK supports creating Graph API subscriptions using those programming languages.

Note

  • Partner topic names must be unique within the same Azure region. Each tenant-application ID combination can create up to 10 unique partner topics.
  • Be mindful of certain Graph API resources' service limits when developing your solution.

What happens when you create a Microsoft Graph API subscription?

When you create a Graph API subscription with a notificationUrl bound to Event Grid, a partner topic is created in your Azure subscription. For that partner topic, you configure event subscriptions to send your events to any of the supported event handlers that best meets your requirements to process the events.

Microsoft Graph API Explorer

For quick tests and to get to know the API, you could use the Microsoft Graph API explorer. For anything else beyond casuals tests or learning, you should use the Graph SDKs as described above.

Next steps

See the following articles: