- What we do
- Who we work with
- Who we are
New features get added to SharePoint Online regularly, and I find it’s worth staying on top of them so we can keep our solutions cutting-edge at CompanyNet. One of the new features I’ve been digging into recently is Webhooks. Webhooks are HTTP callbacks that are automatically triggered when something happens. At the moment, support for Webhooks in SharePoint is limited to SharePoint lists.
On first glance, they seemed like they might fill a void in the SharePoint online developer toolset. I took the opportunity to explore Webhooks with a real-world scenario, and found several oddities with working with them.
This blog post will detail the process I went through, which will hopefully be useful for anyone else looking into this technology.
The requirements for the real-world scenario were simple. We needed to run some custom code every time a task item was updated in a task list on any one of many sites. This code could interact with a variety of different platforms (SharePoint, SQL and Dynamics CRM).
My original plan had been to use the Webhook to add the notification to a service bus queue and get a WebJob to pick up the notifications and process them. After doing a bit more research, it turns out that, when adding a Webhook, SharePoint will try to verify the URL that you passed to it. It does this by passing a validation token to the URL, expecting a response with this validation token. If it doesn’t get the validation token back, you’ll receive an error message saying the URL validation failed. So, instead of adding the notification to a queue, I had to pass it to some code to check for the presence of the token before responding.
This meant a slight tweak was required to the architecture. I introduced an Azure Function to verify the message before adding it to the queue. I wanted to keep the Azure Function light in terms of verification, so all it does is check for the validation token – if it’s present, it returns it, otherwise it adds the message to the queue. The main content to my Azure Function is as follows:
So now that I had the messages in my queue, I needed to start creating my WebJob. The WebJob’s first task is to get the relevant updated task items to see if they are completed (as opposed to just being updated). The message that gets added to the queue is an array of type WebhookNotification. I created the following object to match the message:
The message can then be converted into a Notification object:
Great – so I had the Webhook message, and could access all its properties. Now I just needed to understand what had changed, and do some business logic dependent on whether the task was completed. The WebhookNotification class makes the following properties available to us:
Looking at the properties passed there are a few areas to be careful around:
The solution I’ve seen suggested for the third point above is to use the GetChanges endpoint, which exists on the List. This endpoint can be queried using the ChangeQuery object, which has several properties that can be set to filter out certain changes (i.e. Item, List, Folder, File). However, this query is where we get to the next quirk of this approach. We should be setting the ChangeTokenStart on this query to time-box when we are getting changes from; two approaches are suggested here:
Finally, we’ve got an array of changes whereby we can iterate through them to see if any are changes to an item:
At this stage, I thought I’d be able to get access to the List item through the change item and be able to check if the column “Status” was set to “Completed”. Unfortunately, the change item doesn’t contain this information – it does have a list item ID, and – as you might have worked out by now – this means another call to SharePoint to load the list item.
In conclusion, Webhooks aren’t bad; they’re just not great. If you do plan to use them, some of the downsides to consider are:
I’m going to continue watching Webhooks with interest to see if they become more useful, as with some improvements they could become a handy part of the SharePoint coder’s toolset.
Microsoft Cloud Future thinking Collective intelligence Office 365 Intranets Business intelligence Digital Transformation Technical Business Transformation Office Gold Partner 20th Anniversary Change Management CRM Privacy Microsoft Inspire Partners Director's Briefing Websites Public Sector Training