Using Microsoft Graph Change Notifications? Don’t miss out on broken subscriptions with NEW lifecycle notifications

If you’re already using change notifications for Microsoft Graph, then you’ll know how powerful they can be with their ability to proactively notify you of new events: such as messages in Teams channels, or other events across Microsoft 365.

A subscription is only good whilst it is active. It’s well known that subscriptions have a expiration time, and that applications which use subscriptions need to monitor that and pro-actively either renew their subscription to keep it active, or create a new one should the expiration time be exceeded.

However, there are several other reasons why a subscription might run into trouble. If the subscription was created with delegated user permissions – what happens if that user account is revoked, temporarily locked or suspended? If the subscription was created with application permissions – what happens if that application is disabled, or an administrator revokes consent?

For an application using these subscriptions this would result in … well, nothing. No new messages would be received, because the subscription was no longer able to work properly. For the application, this is an issue. There’s no way to differentiate between no messages because there’s no activity, or no messages because something is broken.  Your application didn’t get any new subscription messages for 24 hours: is there a problem, or is it just a quiet weekend?

Welcome, Lifecycle Notifications

Luckily, Microsoft have a solution to this problem. In an article posted to Microsoft Docs yesterday, we learnt that Microsoft Graph change notifications can now optionally send additional message to an application. These are separate to the notifications about the subscription target (the information about the Teams, User etc), they are metadata about the subscription, letting the application know that something has gone wrong.

For instance, you could receive a subscriptionRemoved message to let you know that your subscription has been removed and no longer exists. Handy if your application relies on the subscription being active.

If your application relies on every single message from a subscription being delivered, then you’ll be interested in this type of notification: the missed event. This is sent when Graph detects that some change notifications might not have been delivered – for instance if your subscription was valid but permissions or other policies prevented your messaging being sent.

Finally, if something has changed about your application’s permissions, for instance an administrator revoking your application’s permission on a resource, you will receive a reauthorizationRequired message. You can use this message as a cue to start the authorisation flow again, or create an event for an administrator to re-authorise your application.

These are three examples which are active today, but more might be added. If you’re building an application which relies on change notification subscriptions, you want to take all lifecycle notifications seriously – including logging any which are you not explicitly handling. This will future-proof you – at the very least you’ll get visibility of events which prevent the smooth running of your subscription.

How to receive Lifecycle Notifications

Lifecycle Notifications are sent as JSON-body messages, here’s an example:

{
"value": [
{
"subscriptionId":"<subscription_guid>",
"subscriptionExpirationDateTime":"2019-03-20T11:00:00.0000000Z",
"tenantId": "<tenant_guid>",
"clientState":"<secretClientState>",
"lifecycleEvent": "subscriptionRemoved"
}
]
}

They are NOT sent automatically, you have to ask for them in your subscription request. You do this by specifying an additional optional parameter in the subscription request: lifecycleNotificationURL.

This URL can be different from your main notificationUrl (but it could also be the same), but it needs to be on the same FQDN. You also can’t PATCH it like you can a notificationUrl.

Should I be using Lifecycle Notifications?

Yes. If you’re doing anything more than trivial operations with change notifications then I think you should be making use of Lifecycle Notifications. Ultimately, a subscription is only any good to an application whilst it is active, and there are many things which can silently prevent a subscription from staying active, without the application ever being aware of them. Lifecycle Notifications provide a way for an application to know that something has gone wrong. It’s up to you whether you make your application super resilient and able to re-subscribe automatically, or just flag the error in a log file for someone to find later, but either way you should start receiving these notifications so that you know what’s going on. After all, nothing is a black box 🙂