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

    Image showing the registration of Microsoft.EventGrid provider with the Azure subscription.

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

    Image showing the successful registration of Microsoft.EventGrid provider with the Azure subscription.

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.

    Screenshot showing the Event Grid Partner Configurations page with the list of partner configurations and the link to create a partner registration.

  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.

      Screenshot showing the Create Partner Configuration page with the Partner Authorization link selected.

  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.

      Screenshot showing the page that allows you to grant a verified partner the authorization to create resources in your resource group.

      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

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://graph.microsoft.com/beta/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://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 as described above.

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.

    Screenshot that shows selection a partner topic in the Event Grid Partner Topics page.

  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.

    Screenshot showing the selection of the Activate button on the command bar or 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.

    Screenshot showing the activation state of a partner topic as **Activated**.

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.

    Screenshot showing the selection of a partner topic on the Event Grid Partner Topics page.

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

    Screenshot showing the selection of Add Event Subscription button on the Event Grid Partner Topic page.

  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.

      Screenshot showing the configuration of an endpoint for an event subscription.

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

      Screenshot showing the configuration of an Event Hubs endpoint.

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

      Screenshot showing the Create Event Subscription page with example configurations.

Next steps

See the following articles: