Notifications in the Graph API
The Graph API allows you to receive notifications when some resource is changed. To start receiving notifications, you need to create a subscription with the Microsoft Graph API. The subscription defines for which entity or a collection you want to receive notifications and where the Graph API should send the notifications. The notifications can be sent either to a web service, Azure Event Hub or Azure Event Grid.
Let's focus on how to sent notifications into the Event Grid and Partner Topic.
Event Grid and Partner Topics
The Event Grid Partner Topics allow you to connect third-party event sources directly to Azure Event Grid. When you create a Microsoft Graph API subscription, a Partner Topic is automatically generated for you. This Partner Topic servers as the entry point for receiving events from the Graph API.
In the Partner Topic, you can define one or more event subscriptions, which allow you to send events coming from the Graph API to supported event handlers. These event handlers can process the events based on your specific requirements.
You will receive events for create, update, and delete state changes and Graph API Partner Topic will send a special event when the Graph API subscription is going to expire. Your event handler can process this event and renew the subscription.
Manage the subscription lifecycle
Every Graph API subscription has an expiration. The advantage of Azure Event Grid and Partner Topic is, that Event Grid will send a special event when the subscription is going to expire in a certain amount of time. Your event handler can proactively process this special event and renew the subscription.
To create Azure Event Grid and Partner Topic, you can use the Azure Portal or automate the creation via Bicep.
Create Azure Event Grid and Partner Topic in Azure Portal
To create Azure Event Grid and Partner Topic, you need to follow these steps:
Log into the Azure Portal
Create a new Azure Resource Group
- Create Azure Event Grid Partner Configurations
Add the Microsoft Graph API Partner Authorization
Select and add the Microsoft Graph API Partner
Create the Event Grid Partner Configuration
Create the Event Grid Partner Topic
To create a Partner Topic, you need to create a subscription with the Microsoft Graph API:
POST /v1.0/subcriptions
The request body is:
{
"changeType": "Updated,Deleted,Created",
"notificationUrl": "EventGrid:?azuresubscriptionid=8A8A8A8A-4B4B-4C4C-4D4D-12E12E12E12E&resourcegroup=yourResourceGroup&partnertopic=yourPartnerTopic&location=theNameOfAzureRegionFortheTopic",
"lifecycleNotificationUrl": "EventGrid:?azuresubscriptionid=8A8A8A8A-4B4B-4C4C-4D4D-12E12E12E12E&resourcegroup=yourResourceGroup&partnertopic=yourPartnerTopic&location=theNameOfAzureRegionFortheTopic",
"resource": "users",
"expirationDateTime": "2024-10-30T00:00:00Z",
"clientState": "secretClientValue"
}
The request body is similar to the one when you create a notification through webhooks. The difference is in the notificationUrl and lifecycleNotificationUrl properties. The value of these properties is the Event Grid endpoint where the events should be sent. They also contains a name of the Partner Topic that will be created once the request is sent.
The notificationUrl is the endpoint where the events are sent, and the lifecycleNotificationUrl is the endpoint where the lifecycle events are sent.
EventGrid:?azuresubscriptionid=8A8A8A8A-4B4B-4C4C-4D4D-12E12E12E12E&resourcegroup=yourResourceGroup&partnertopic=yourPartnerTopic&location=theNameOfAzureRegionFortheTopic
The azuresubscriptionid is the Azure subscription ID, resourcegroup is the name of the resource group where the Partner Topic will be created, partnertopic is the name of the Partner Topic, and location is the name of the Azure region where the Partner Topic will be created.
If I want to create a Partner Topic with name userevents in the resource group graphapiusernotification in the region East US, the notificationUrl and lifecycleNotificationUrl will be:
{
"changeType": "Updated,Deleted,Created",
"notificationUrl": "EventGrid:?azuresubscriptionid=8A8A8A8A-4B4B-4C4C-4D4D-12E12E12E12E&resourcegroup=graphapiusernotification&partnertopic=userevents&location=eastus",
"lifecycleNotificationUrl": "EventGrid:?azuresubscriptionid=8A8A8A8A-4B4B-4C4C-4D4D-12E12E12E12E&resourcegroup=graphapiusernotification&partnertopic=userevents&location=eastus",
"resource": "users",
"expirationDateTime": "2024-10-30T00:00:00Z",
"clientState": "secretClientValue"
}
You should receive the response with the status code 201 Created.
- Activate the Event Grid Partner Topic
Now go to the resource group (or refresh it) and you should see the Partner Topic created through the subscription.
Click on the Partner Topic and in the detail, click on the Activate button.
Once the Partner Topic is activated, you will start receiving notifications from the Microsoft Graph API. Try to add or update a user in your tenant and check the Event Grip Partner Topic metrics.
Conclusion
The Azure Event Grid and Partner Topics are a alternate way to receive notifications from the Microsoft Graph API.
Notifications through the Event Grid are useful when
- You're developing an event-driven solution that requires events to react to resource changes
- You want to route events to multiple destinations using a single Graph API subscription
- You want to avoid managing multiple Graph API subscriptions
- You want to process different event types by one or more different applications, webhooks, or Azure services
Next time, I will show how to automate the creation of Azure Event Grid and Partner Topic via Bicep and the Microsoft Graph API PowerShell SDK.
