Posted by on Dec 9, 2015 in #Office365Dev | 3 comments

There is a way for your service to learn about changes in a user’s mail, calendar or contacts – the Outlook Notifications REST API.

Using this API you can register HTTP callbacks for your own service, to be notified when the user makes changes. The whole concept is called webhooks. I’ll walk you through the basics, but you can learn more about it here: http://culttt.com/2014/01/22/webhooks/ 

In this post we will create an ASP.NET Web API that will respond to notifications sent from Office 365 (this will work for Outlook.com as well).

Please note, the HTTP requests we will be making in this post towards the Outlook endpoints needs to be authenticated. You will need to attach a valid OAuth access token in the authorization header of your requests, learn more at: https://msdn.microsoft.com/office/office365/APi/use-outlook-rest-api#ShortRegAuthWorkflow

API method

The first step is to create and host your Web API somewhere – it needs to be deployed and validated by the Outlook Notifications REST API before we can get notifications sent to it. In terms of validation, it’s pretty straight forward. When we ask the Outlook Notifications REST API to start sending notifications (by creating a subscription) to your API – it will go ahead and send a validation token to it. Your job is to respond with the same validation token within 5 seconds, if you can achieve that – a subscription for notifications will be created and returned to the client application (creating the subscription).

I started out by creating a new ASP.NET Web API controller and a POST method. Both the validation and notification requests will be sent as POST messages.

As for the validation token, I will accept it as an optional parameter. If it’s present in the request, we know that a validation of the URL (Web API) is happening. If not, we can assume that we’re getting a notification from an active subscription.

So if a validation token parameter is present, let’s return it right away in the proper way – set the content type header to text/plain and return HTTP 200 as the response code.

As for no present validation token in the request, let’s start parsing the request body and look for notifications. I recommend you to pay attention to the client state header in the request (named ClientState). If you create the subscription with a client state property, it will be passed along with the notification request. This way you can verify the legitimacy of the notification.

Models

In addition to the API controller, I implemented the following models to deal with the notification requests (parsing the JSON).

At this point, you will need to deploy your Web API to a hosting provider (for instance Microsoft Azure: https://azure.microsoft.com/en-us/).

Create a subscription (using Fiddler)

To kick things off – I created the notification subscription by sending a request using Fiddler. If you are not familiar with it, Fiddler is a web debugging tool that lets you do all sorts of things. One of its features is to compose HTTP messages.

You would implement the same using any programming language in your client application or service. Your request (POST to https://outlook.office.com/api/v2.0/me/subscriptions) should include the following:

  • An (OAuth) access token in the authorization header.
  • A content type header set to application/json.

Include a JSON object with a few properties in your request body. Set @odata.type to #Microsoft.OutlookServices.PushSubscription. Set Resource to the entity or collection that you wish to subscribe to (the entire calendar in this case). Make sure that your access token has the sufficient scope (Mail.Read, Calendars.Read, Contacts.Read) for the resource. Here is a couple of examples:

Set NotificationURL to the URL of your API method endpoint. Set ChangeType to the type of change that you want to subscribe to (Created, Update, Deleted). Optionally set the ClientState property, the value will be sent with each notification generated by the subscription.

Response

I used Visual Studio 2015 to attach a debugger to my Azure web app (see https://azure.microsoft.com/sv-se/documentation/articles/web-sites-dotnet-troubleshoot-visual-studio/#remotedebug), which is hosting my Web API. I set up a breakpoint to catch and validate the flow. After the validation happened, I received notifications and was able to investigate the response.

Wrap up

Like this your service can now subscribe to changes happening in different resources in Outlook. If not specified otherwise, these subscriptions will be valid for up to 3 days. If you need them to last longer, you can renew them for another 3 days by sending a PATCH request to: https://outlook.office.com/api/v2.0/me/subscriptions/your_subscription_id

Using this event driven approach is a much more solid way of dealing with changes in the resources in Outlook. As opposed to polling the Outlook REST APIs directly, this is much more lightweight (especially when the amount of items is large). With scale, this approach becomes essential for a sustainable service architecture.

As always, include a valid authorization header when making the requests. You can learn more about the Outlook Notifications REST API and its operations at: https://msdn.microsoft.com/en-us/office/office365/api/notify-rest-operations

A sample of an ASP.NET Web API project validating and responding to Outlook notifications is available at: https://github.com/simonjaeger/Outlook-Notifications-DotNet-WebAPI

-Simon Jaeger