Upcoming SharePoint WebHooks

close up photograph of generic javascript code on computer monitor

This summer is looking like an awesome period for new development features and the Office PnP team recently published a web cast on SharePoint Web Hooks in Office 365, although this is not yet released, the public preview for first release tenants will be due this summer.

So what are Web Hooks?

Web Hooks are an asynchronous push mechanism to provide notification to a remote endpoint for changes. In the context of SharePoint, this would be similar to Remote Event Receivers that trigger a remote call when changes are made to the subscribed resource i.e. lists or web.

Great things using Web Hooks?

Incremental Retry – this will notify the subscribing endpoint of a change, there is an incremental retry and back off mechanism to re-POST the notification to the remote service. The remote service will need to respond within 5 seconds with a HTTP/1.1 200 to acknowledge receipt of POST.

This is really nice over the Remote Event Receivers because if your endpoint is overloaded or there is a transmission failure between SharePoint and your endpoint, the message isn’t immediately lost.

Small Payload – The payload for the notification event is very small, with JSON response containing:

  • subscriptionId (Guid)
  • clientState (Guid)
  • expirationDateTime (DateTime)
  • resource (Guid)
  • tenantId (Guid)
  • siteUrl (String)
  • webId (Guid)

Secure – Each payload doesn’t provide any detail about the change itself therefore details about the list item or document and metadata are not included in the events.

Easy to implement – the model for Web Hooks are not specific to Microsoft and is used with other services such as WordPress, GitHub, MailChimp etc. There are NO WCF endpoint and can use regular HTTP services, therefore you don’t have to be a SharePoint developer to implement this.

OneDrive and Outlook already supported in Production – Other Office 365 services use Web Hooks at the moment, with well documented APIs and code samples

Gotchas when using Web Hooks?

Subscription expires 6 months – when a subscription to a Web Hook is made, the maximum length of the subscription is 6 months. The web casts suggests that you could re-subscribe during one of the event notifications however, this is flawed if the list or library becomes stale and is unused for more than 6 months. A service or web job will need to be created to maintain these

Undecided yet about the incremental back-off limits – Once the limits are reached for the retry mechanism the message will be lost, at the moment Microsoft haven’t yet published details on the limit for the retry. However this may come towards the release of the service in the summer.

Notifications and changes have no relationship – The notification doesn’t provide details about the change, a CSOM call to GetChanges() is required once a notification is received. However, you will need to grab and store change tokens on creation and after each call to the CSOM API, each notification could represent 1 or many changes.

Web Jobs need to run in single instance mode – The web cast noted another limitation as the notification event isn’t specific to a change if you use Web Jobs and Queues its possible that multiple web jobs could request the same changes therefore leading to concurrency issues.

At the moment the preview will only support lists, other types of events are due later. This isn’t a limitation as such as Microsoft simply haven’t include other object types such as webs, but its worth mentioning.

Can we play?

For the moment, the feature isn’t yet released for first release Office 365 tenancies, the PnP team will release a code sample to try out the mechanism when this has been rolled out. You will need the following services in order to play with the feature and the sample:

  • Office 365 Subscription with SharePoint Online
  • Azure Web App for Application and Web Jobs
  • Azure SQL Database to store the change tokens
  • Azure Storage Queue to store received messages ready for processing.

Web Hooks are in play with Outlook and OneDrive in production, you can use these to gain an understanding of the principles of the mechanism.

I recommend watching the PnP Web Cast to get more detail about the implementation of the mechanism behind using Web Hooks and seeing the demos to get ahead of the release.

I look forward to playing with this and determining potential for solutions when its available.

“Sharing is Caring”


%d bloggers like this: