Some notes regarding the Microsoft Graph Subscription and webhook

For certain Azure AD resources or Directory Objects you can use Microsoft Graph to create Subscriptions to receive change notifications event. Below are some notes to be aware of:

Subscription object

Lifetime

Each subscription object (except for Security alerts) is only valid for 3 days maximum, so make sure you renew the subscription before it expires to keep receiving change notifications. See https://docs.microsoft.com/en-us/graph/api/resources/subscription?view=graph-rest-1.0 for more detail on maximum subscription length per resource type.

Subscription Update

The only updated operation on updating a subscription is to extend its expiry time. See https://docs.microsoft.com/en-us/graph/api/subscription-update?view=graph-rest-1.0&tabs=http for more info.

notificationUrl property

This is the webhook URL the client application sends to Microsoft Graph when creating a subscription. Microsoft Graph Service calls back to this endpoint to verify its validity during Subscription creation and uses this endpoint to notify the client applications about event changes. This callback mechanism is not built for a sophisticated scenario where the notificationUrl is protected by some additional security measure. Below are a couple of things that can lead to failure when setting up change notification URL:

• the notification URL requires a client certificate
• the notification URL requires some form of authentication
• there is a problem with a certificate used to bind the notification URL, for instance untrusted CA, invalid hostname, or expired certificate, etc…

Change notification for User and Group Objects

The User and Group objects only support ‘updated’ and ‘deleted’ change notification (see changeType propery in https://docs.microsoft.com/en-us/graph/api/resources/subscription?view=graph-rest-1.0). When an object is created, Azure AD does not create the object along with its properties at the same time. It creates the skeleton object first and then updates the object with certain properties. For this reason, the client application can receive ‘updated’ event for newly created objects.

When an object is deleted, Azure AD moves the object to a ‘soft’ delete state. After 30 days the object is then permanently deleted (‘hard’ delete). An object in the ‘soft’ delete state can be recovered. Microsoft Graph sends an ‘updated’ event when an object is moved to the ‘soft’ delete state and then ‘deleted’ event when it’s permanently deleted. To query for all the supported objects in the ‘soft’ delete state, refer to List Deleted items documentation and refer Restore Deleted objects documentation for how to recover them.

See https://docs.microsoft.com/en-us/graph/known-issues#change-notifications for more info.