SharePoint webhooks: Why it’s time to get hooked

Posted by Eric Overfield on Jan 31, 2017 5:31:42 PM

It continues to be an exciting time for SharePoint developers, especially with the seemingly inevitable task of moving our organizations to the cloud. A popular feature of on-premises SharePoint has been the ability to register event receivers—that being the ability to have SharePoint notify our custom processes when an action occurred. With SharePoint Online, this has been much more difficult, but with the recent release of SharePoint webhooks, we now have Microsoft’s answer to our concerns.

Last September, webhooks were released for Developer Preview, and since then we have been waiting for their official release. The wait is over: SharePoint webhooks are production-ready and generally available. As a new cloud-ready event-handling concept introduced to the SharePoint world, webhooks offer a way to improve your organization’s work processes within SharePoint Online.

What are webhooks?
Webhooks, utilized throughout many web development ecosystems, allow developers and the applications they create to be more aware of what is going on within a given platform. Whether that platform is WordPress, GitHub, or now SharePoint Online, webhooks help customized applications and processes stay connected to specific events, content changes or updates. In fact, some of the most popular social platforms and applications provide webhooks, including Facebook, Slack and even Instagram.

Webhooks are based on a notification system, whereas when an event occurs within a web application, a notification is sent by the system and a custom callback may then be executed. In simpler terms, web developers can use webhooks to receive notifications on specific events that take place in a given application or platform, such as SharePoint. As an example, SharePoint webhooks offer a new way to manage a SharePoint list through simple event notifications. A SharePoint webhook can be set to let a custom process know when an addition ("ItemAdded") or deletion ("ItemDeleted") of a document or file occurs within a Team Site. The custom process—say, a web service hosted on Azure, or even an Azure Function—would then react accordingly with a specific custom callback.

The process is initiated when web developers register their webhooks with simple calls to a REST API. Through custom callbacks, webhooks improve the way service-oriented tasks are tracked, troubleshooted and managed. This ability to register callbacks based on events is SharePoint Online’s way of allowing for cloud-enabled remote event receivers.

A “push not pull” method
Using Webhooks allow processes to stop asking the dreaded question, "Are we there yet?" If you have ever taken a family road trip (especially with little kids), then you must be familiar with this question. SharePoint Webhooks utilize a “push not pull concept” – what this means is that custom processes do not have to continually “pull” (i.e., request) information from SharePoint, asking if an event took place.

Webhooks lets you know when an event happened, rather than persistently asking for the information you need, such as, "Is the file updated yet?" or "Has a document been deleted yet?", you can create a webhook that notifies you once a related event occurred. Essentially, you will never have to be a victim of the “Are we there yet?” question again (well at least in this area of your life).

Starting Your First SharePoint Webhook

While webhooks are a new concept to SharePoint, they are, in general, easy to set up. Be aware SharePoint webhooks are currently only available for SharePoint Online. Creating a new subscription with SharePoint webhooks is reasonably straightforward. You will need three pieces of information: a resource endpoint, a server notification URL, and an expiration date.

The resource endpoint is the URL of the resource you want a webhook tied to, i.e. a SharePoint List. The server notification URL is the service endpoint of your custom callback. When something happens to your resource endpoint, SharePoint will send an HTTP POST to your resource endpoint. Finally, you want to provide an expiration date that is less than six months from the registration date. By default, each webhook will expire after six months.

Once you register a subscription, the service notification URL will begin receiving requests from SharePoint when registered events occur. Each notification request will contain a “validationToken” that your callback may use to validate the notification. Your custom code, hosted on Azure, in your own on-prem environment, or even hosted as an Azure Function, may now react to events in SharePoint automatically, once the event occurs.

Be aware that SharePoint webhooks are asynchronous, meaning they can only be registered for “-ed” events, and not “-ing” events, i.e. notify me when a list item has been creat-ed. We are unable to registered a webhook for when creat-ing a list item so that a custom callback could interact with SharePoint “while” the event in question is happening.

Moving forward with webhooks
As Office 365 and SharePoint continue to evolve, we will continue to see the adaptation of modern techniques in SharePoint, such as webhooks. The opportunities to create more productive work environments are endless, and with the increasing benefits of moving to the cloud, it is imperative SharePoint developers be agents of change rather than roadblocks.

Additional resources
SharePoint webhooks overview

SharePoint webhooks list example

PnP webcast: SharePoint webhooks

Eric Overfield an Office 365 MVP and the President and co-founder of PixelMill, a digital branding consultancy specializing in Responsive Web Design, UI/UX and Branding for SharePoint websites and portals.

Topics: webhooks

Thoughts? Leave a comment: