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.

Important

Microsoft Graph API's ability to send events to Azure Event Grid is currently in private preview. If you have questions or need support, please email us mailto:ask-graph-and-grid@microsoft.com?subject=Support Request.

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 should I use Microsoft Graph API 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

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.

Register the Event Grid resource provider

Unless you've used Event Grid before, you'll need to register the Event Grid resource provider. If you’ve used Event Grid before, skip to the next section.

In the Azure portal, do the following steps:

1. On the left menu, select Subscriptions.

2. Select the subscription you want to use for Event Grid from the subscription list.

3. On the Subscription page, select Resource providers under Settings on the left menu.

4. Search for Microsoft.EventGrid, and select it in the provider list.

5. Select Register on the command bar.

   

6. Refresh to make sure the status of Microsoft.EventGrid is changed to Registered.

   

Authorize partner to create a partner topic

You must grant your consent to the partner to create partner topics in a resource group that you designate. This authorization has an expiration time. It's effective for the time period you specify between 1 to 365 days.

Important

For a greater security stance, specify the minimum expiration time that offers the partner enough time to configure your events to flow to Event Grid and to provision your partner topic. Your partner won't be able to create resources (partner topics) in your Azure subscription after the authorization expiration time.

Note

Event Grid started enforcing authorization checks to create partner topics around June 30th, 2022.

1. Sign in to the Azure portal.

2. In the search bar at the top, enter Partner Configurations, and select Event Grid Partner Configurations under Services in the results.

3. On the Event Grid Partner Configurations page, select Create Event Grid partner configuration button on the page (or) select + Create on the command bar.

   

4. On the Create Partner Configuration page, do the following steps:

   1. In the Project Details section, select the Azure subscription and the resource group where you want to allow the partner to create a partner topic.

   2. In the Partner Authorizations section, specify a default expiration time for partner authorizations defined in this configuration.

   3. To provide your authorization for a partner to create partner topics in the specified resource group, select + Partner Authorization link.

      

5. On the Add partner authorization to create resources page, you see a list of verified partners. A verified partner is a partner whose identity has been validated by Microsoft. Follow these steps to authorize Auth0 to create a partner topic.

   1. Select the verified partner (Auth0, SAP, Tribal Group, or Microsoft Graph API) from the list of verified partners.

   2. Specify authorization expiration time.

   3. select Add.

      

      Important

      Your partner won't be able to create resources (partner topics) in your Azure subscription after the authorization expiration time.

6. Back on the Create Partner Configuration page, verify that the partner is added to the partner authorization list at the bottom.

7. Select Review + create at the bottom of the page.

8. On the Review page, review all settings, and then select Create to create the partner registration.

Enable Graph API events to flow to your partner topic

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://graph.microsoft.com/beta/subscriptions

x-ms-enable-features: EventGrid

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 headers and payload properties:

• x-ms-enable-features: Header used to indicate your desire to participate in the preview capability to send events to Azure Event Grid. Its value must be EventGrid. This header must be included with the request when creating a Microsoft Graph API subscription.
• 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 that generates events to announce state changes.
• expirationDateTime: the expiration time at which the subscription expires and hence the flow of events 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://graph.microsoft.com/beta. 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://graph.microsoft.com/beta");

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.

Activate a partner topic

1. In the search bar of the Azure portal, search for and select Event Grid Partner Topics.

2. On the Event Grid Partner Topics page, select the partner topic in the list.

   

3. Review the activate message, and select Activate on the page or on the command bar to activate the partner topic before the expiration time mentioned on the page.

   

4. Confirm that the activation status is set to Activated and then create event subscriptions for the partner topic by selecting + Event Subscription on the command bar.

   

Subscribe to events

First, create an event handler that will handle events from the partner. For example, create an event hub, Service Bus queue or topic, or an Azure function. Then, create an event subscription for the partner topic using the event handler you created.

Create an event handler

To test your partner topic, you'll need an event handler. Go to your Azure subscription and spin up a service that's supported as an event handler such as an Azure Function. For an example, see Event Grid Viewer sample that you can use as an event handler via webhooks.

Subscribe to the partner topic

Subscribing to the partner topic tells Event Grid where you want your partner events to be delivered.

1. In the Azure portal, type Event Grid Partner Topics in the search box, and select Event Grid Partner Topics.

2. On the Event Grid Partner Topics page, select the partner topic in the list.

   

3. On the Event Grid Partner Topic page for the partner topic, select + Event Subscription on the command bar.

   

4. On the Create Event Subscription page, do the following steps:

   1. Enter a name for the event subscription.

   2. For Filter to Event Types, select types of events that your subscription will receive.

   3. For Endpoint Type, select an Azure service (Azure Function, Storage Queues, Event Hubs, Service Bus Queue, Service Bus Topic, Hybrid Connections. etc.), or webhook.

   4. Click the Select an endpoint link. In this example, let's use Azure Event Hubs destination or endpoint.

      

   5. On the Select Event Hub page, select configurations for the endpoint, and then select Confirm Selection.

      

   6. Now on the Create Event Subscription page, select Create.

      

Next steps

See the following articles:

• Azure Event Grid - Partner Events overview
• Microsoft Graph API webhook samples. Use these samples to send events to Event Grid. You just need to provide a suitable value notificationUrl according to the request example above.
• Varied set of resources on Microsoft Graph API.
• Microsoft Graph API webhooks
• Best practices for working with Microsoft Graph API
• Microsoft Graph API SDKs
• Microsoft Graph API tutorials, which shows how to use Graph API in different programming languages.This doesn't necessarily include examples for sending events to Event Grid.