Microsoft Graph Webhooks - What, Why, How & Best Practices

Learn about a feature that's been in Microsoft Graph for a very long time. But it's always surprising to me how many people aren't aware of it.

by Andrew Connell

Last updated April 15, 2024

12 minutes read

How Microsoft Graph webhooks work

The webhook allows you to issue a query to Microsoft Graph and then requests a notification when the query results change. For instance, if you query a list of all files in a SharePoint Embedded Container or SharePoint document library, and a new file is added, Microsoft Graph will notify you that happened.

Which Is It? Webhook or Change Notifications?

This is frustrating and frankly a little annoying. Technically, they’re just webhooks. Some product manager or marketing person at Microsoft tried to get creative to give the a more descriptive name. But the only people implementing these are web developers, and webhooks are the industry term so they should have just stuck with that.

Webhooks allow applications to be notified when data is created or modified in Microsoft Graph. When an entity of interest is created, updated, or deleted, Microsoft Graph sends an HTTP POST to a designated endpoint. Your custom endpoint listens for these messages and responds according to your business requirements.

What can you receive notifications for?

Notifications can be received for messages, events, contacts, users, groups, conversations, OneDrive files, alerts, and more. This keeps you updated and synchronized with data accessible via Microsoft Graph. It also eliminates the need for a polling infrastructure, where you frequently send requests to Microsoft Graph to check for the latest changes. Instead, you can request changes from Microsoft Graph when your application receives a notification. This ensures you never miss a modification to data exposed or accessible via Microsoft Graph.

Web service

Most of the work will occur within a web service that you create. This web service holds two main responsibilities.

Respond to Validation Request

Initially, when a webhook subscription is created, Microsoft Graph sends a confirmation HTTP POST to your web service to confirm its functionality.

Process Webhook Submissions

The web service’s second responsibility is to listen for and process the webhook notifications that Microsoft Graph sends.

Webhook subscriptions

To receive notifications from Microsoft Graph when something happens, you need to create a webhook. This is done by creating a subscription with Microsoft Graph. The subscription informs Microsoft Graph about the entity or collection for which you want to receive notifications and provides the address of your web service to post these notifications.

When creating the subscription, you specify the subscription duration. Different entities have different maximum durations. For instance, files in OneDrive (driveItems) can have a maximum subscription expiration time of 42,300 minutes (approximately 30 days) from when the subscription is created.

Create subscription

Next, create a webhook subscription by submitting an HTTP POST request to the subscriptions endpoint: https://graph.microsoft.com/v1.0/subscriptions.

The following HTTP POST creates a subscription to receive webhooks on the https://graph.microsoft.com/v1.0/users endpoint when users are updated:

POST https://graph.microsoft.com/v1.0/subscriptions
Authorization: bearer eyJ0eXAiOiJ[..]
Content-Type: application/json

{
  "changeType": "updated",
  "clientState": "SecretClientState",
  "notificationUrl": "https://voitanos.ngrok.io/api/notifications",
  "resource": "/users",
  "expirationDateTime": "2024-05-01T00:00:00.0000000+00:00"
}

Manage the subscription lifecycle

Webhook subscriptions will be good for a specified amount of time. For most resources, the maximum subscription length is 3 days, but you should check with each resource for the supported subscription maximum length. After that time, the subscription is automatically purged from Microsoft Graph. This means if your application does nothing after creating the subscription, it will only receive notifications up to the expiration time specified when the subscription is created.

You should have a process that is going to monitor the subscriptions to ensure that it isn’t expired or isn’t going to expire in a certain amount of time.

Get one or multiple subscriptions

To get a list of all your current subscriptions, submit an HTTP GET to the subscriptions endpoint…

GET https://graph.microsfot.com/v1.0/subscriptions
Authorization: bearer eyJ0eXAiOiJ[..]

Renew webhook subscription

Now let’s look at the process for renewing a subscription. This is done by submitting an HTTP PATCH request to the endpoint of the subscription.

PATCH https://graph.microsoft.com/v1.0/subscriptions/47e861c4-2db2-455a-8774-57658ba185a1
Authorization: bearer eyJ0eXAiOiJ[..]
Content-Type: application/json

{
  "expirationDateTime": "2024-06-01T00:00:00.0000000+00:00"
}

Delete subscriptions

Deleting subscriptions is as simple as submitting an HTTP DELETE to the subscription endpoint:

DELETE https://graph.microsfot.com/v1.0/subscriptions/{{subscriptionId}}
Authorization: bearer eyJ0eXAiOiJ[..]

Delta query: tracking changes in Microsoft Graph

Many custom applications have a need to track and replicate changes between two systems. One way developers can monitor a source system for changes is by polling the system to detect changes.

As I previously covered, as an alternative to the polling pattern, developers can leverage webhooks in Microsoft Graph to be notified when entities change. While this addresses one part of the problem, what happens in the case where a webhook subscription expires? In this case, your application may miss changes to entities when the subscription was not active.

Introducing delta query

Delta query is supported on many different types of entities, include email messages, groups, users, events, and files objects in Microsoft Graph.

The way it works is that an application submits an HTTP GET request to a particular endpoint, /users for example. In the request, the endpoint has the /delta function added to the end of the URL.

Submitting a delta query request

Let’s look at a sample request. The following request will get a list of all users from Microsoft Graph.

GET https://graph.microsoft.com/v1.0/users/delta
Authorization: bearer eyJ0eXAiOiJ[..]

Conclusion

In conclusion, this article has provided a comprehensive overview of Microsoft Graph’s webhooks and delta query features. These features offer a robust and efficient way to track changes in your Microsoft Graph data. By understanding and implementing these features, you will be able to create more responsive and reliable applications.