Subscribe to Microsoft Graph API Change Notifications Using PHP and Laravel

In the previous tutorial, I demonstrated a basic integration with the Microsoft Graph API using the OAuth2 authorization code grant type. Now, I’ll enhance that integration by adding support for Microsoft Graph API change notifications.

If you don’t already have a configured project, I recommend starting with the previous post: How to Integrate Microsoft Graph API with PHP Laravel: Step-by-Step Tutorial.

Prerequisites

1. You need a Microsoft Azure application to access the Microsoft Graph API.

2. You should have a Laravel project with the Microsoft Graph API client integrated.(Follow the previously mentioned guide to set up a new project with Graph API integration.)

Requesting OAuth2 Mail Resource Scopes

In this tutorial, we will subscribe to mail inbox changes. During authentication, we need to request additional mail scopes to interact with the mail resource. If you followed the previous tutorial, the Mail.ReadBasic and Mail.Read scopes should already be configured in the services.microsoft configuration.

Creating a Subscription Page

We’ll create a subscription by submitting a form on a dedicated page.

Update the routes/web.php with the new endpoint:

Create a new Blade view subscriptions/new.blade.php:

Although the form has only one button, it is sufficient for the purposes of this tutorial.

Add a link to this page in home.blade.php before the logout link. Ensure it is only visible when the Microsoft authorization context is present.

Creating a Graph API Subscription

Next, we need to call the Microsoft Graph API to create an actual subscription. The subscription form will send a POST request to the /subscription endpoint. Let's add the actual subscription creation logic.

What you need to do to create a subscription:

• Instantiate a new Subscription object to specify the desired parameters.

• Set the subscription change type (e.g., what notification types to receive).

• Configure the notification URL, which Microsoft Graph API will call when the selected change type occurs.

• Set the resource name to /me/messages to subscribe to changes in the mailbox for the authorized account.

• Define the subscription expiration date (e.g., 15 minutes in this example).

• Invoke the Microsoft Graph API to create the subscription and redirect the user to the subscription show page (we will add this page next).

  
  

Let's add the actual subscription creation logic to the routes/web.php:

Displaying the created Microsoft API Subscription

Add a show subscription endpoint in the routes/web.php:

In this endpoint, I fetch the subscription object from the Microsoft Graph API and render the show page.

Define subscriptions/show.blade.php:

This page displays the most important subscription properties that's is enough to be sure that subscription is created.

Handling Incoming Change Notifications (Webhooks)

Add the webhook endpoint to process incoming notifications:

For this tutorial, it's enough to ensure that we receive the Microsoft Graph webhooks.

Disable CSRF protection for the webhook endpoint:

Setting Up Notification URL

To receive webhooks locally, expose your server to the internet. Tools like Hookdeck can help by receiving Microsoft notifications and redirecting them to your server via the hookdeck-cli utility.

When you create a notification URL, please make sure to update the subscription creation endpoint with your actual URL.

Testing Notifications

To test the integration, follow these steps:

1. Start your application server.

2. Start the notification URL proxy listener (hookdeck-cli).

3. Authorize a user with the Microsoft Azure application using the homepage links.

4. Navigate to the subscription creation page and create a new subscription.

5. You should be redirected to the show page displaying the subscription’s properties.

6. Go to your mail account and create a new draft email or send an email from another account.

You’ll receive incoming requests to the webhook endpoint in your Laravel app. Use the Hookdeck dashboard to inspect incoming webhooks. Below is a sample payload structure for an incoming webhook notification.

Wrap Up

In this tutorial, we integrated Microsoft notification subscriptions into a Laravel application.

To fetch changed data, use the properties from the incoming webhook payload to invoke the related Microsoft Graph API resource endpoint. Alternatively, you can configure Microsoft Graph API to send rich change notifications, which include the actual payload. However, these types of subscriptions involve additional encryption and decryption steps.