Welcome to this technology talk series hosted in Netwoven, where we will learn about how webhooks are used in SharePoint Online, if you have come here from our earlier talk {Read Part 1 here} about webhooks then Welcome back!!! For sake of housekeeping, just to remind you, if you like this read, please leave a reply about who you are, what role do you play in your organization, how you use SharePoint every day and what you like and dislike about SharePoint (trust us, we would really like to know you). And if you dislike this read, then please let us know why and how we can improve it.
This is the second part of the webhook technology talk series where we will journey further to learn more about webhooks. So, our agenda today will be
- Using webhooks to subscribe to a SharePoint Online list/library
- Taking a closer look at how we communicate with SharePoint Online using webhooks
Let’s refresh our memory about webhooks briefly, we know that webhooks is a pattern/practice that has been around for a while now that allows us to develop event-driven applications. So, the way we apply it to SharePoint Online is through our client application/endpoint that will act as our medium for communicating with SharePoint Online and receive event notifications.
With webhooks, we first “Subscribe” our client/application to a SharePoint Online List/Library so that SharePoint can post change notification to us every time a particular resource that we have subscribed to has changed.
In our case, let’s say we subscribe our application to a SharePoint Online Document Library. To make our subscription we send a POST message to SharePoint, which includes a body that contains Resource: …./web/Lists/getbytitle(‘Documents’)
Notification URL: (this is our notification endpoint where SharePoint sends change notification)
Expiration Date: Webhook subscriptions auto expire as a security measure in 6 months. So expiration date can only be up to 6 months out. To continue your subscription to the webhook, your application must re-subscribe to the resource before expiration date
Once we subscribe to a SharePoint resource, SharePoint calls the notification URL we provide and it passes a query parameter called validation token. This validation token is just a random GUID and needs to be sent right back to SharePoint by our application in the message body under 5 seconds. It is crucial to make sure the application responds back with the validation token within 5 seconds, otherwise we lose our subscription
After SharePoint successfully receives the message with the validation token, it will respond back to our application with the following
Id – ID of the subscription
Expiration date
Notification URL
Resource – GUID of the List/Library subscribed to
Looks easy doesn’t it!!!
Once we have our subscription ready, what does a notification look like when SharePoint notifies our application of a change?
So, the notification that comes from SharePoint Online to the notification URL (our application endpoint) is set to transmit on a timer and it may take upwards of 5 min for SharePoint to send the notification once a change event has been triggered. This can be a concern if the application is looking for real-time notifications. So, keep that in mind when you apply webhooks to your solution.
But, once our application receives the notification from SharePoint, we see a POST from SharePoint that contains the resource, tenant ID, expiration date and other fun stuff. Unfortunately, this message body itself does not provide enough information to get details about the change from it, but there is enough to use to go back to SharePoint and extract the change details from the resource.
Again, once our endpoint receives this notification, it must reply to SharePoint with an empty 200 OK to say yes I have received the notification. Timing is crucial to keep the subscription open, hence, the reply must be made within 5 secs to let SharePoint know that our application is still listening.
We will conclude this talk here and we hope you enjoyed this read and learned something new today. Come back for the Part 3 – Our thoughts on Webhooks in SharePoint Online where we will talk about what we think some of the current advantages/disadvantages of SharePoint Online are and mention some best practices we have come across.
Thanks
Read Part I : Webhooks in SharePoint Online – An Introduction
