SharePoint is home to a vast array of content – from in-progress draft documents on personal sites, to team task items, to official specifications and corporate records. Our goal is always to provide easy, flexible APIs for working with this content. For querying and retrieving this data, we feature robust REST- and client object model (CSOM) based APIs, but, frequently, developers need more capabilities that go beyond this. A common developer requirement is to pull facets of a business process together for their organization, and so they need to be notified when changes in SharePoint happen. For example, processes should start when a user has saved a document, or when a list item is updated with a certain value. These notifications need to be consistent and easy to manage via straightforward APIs.
Where possible — in support of simplicity and consistency — we work to take existing, evolving standards and practices and support them within SharePoint. For these reasons, we are introducing the new SharePoint Webhooks Developer Preview. Webhooks are an increasingly common developer notification technology used across the industry in various web applications to inform each other about changes in their respective systems. In SharePoint, developers can use the SharePoint Webhooks Developer Preview to be informed when items and documents are added, edited, deleted, and more. These webhooks calls could be used as inputs to business processes, or used to provide more real-time notifications to users when changes happen.
You can get started with the SharePoint Webhooks Developer Preview today by visiting our documentation at https://aka.ms/spwebhooks. We have concise reference implementations of webhooks on Github at https://aka.ms/spwebhooksample. You will find an overview and details around SharePoint webhooks, as well as simple tutorials and examples. Webhooks are available in all First Release Office 365 tenants, and we’re working to expand support of Webhooks to more tenancies over time.
Webhooks rely on REST-based APIs for subscriptions, so signing up to a webhook is as simple as a POST request:
POST /_api/web/lists('list-guid')/subscriptions
followed by a basic validation protocol to ensure that your services can support a webhook subscription.
In the initial preview, developers can sign up to receive webhook notifications on common list item events, such as ItemAdded/Updated/Deleted/CheckedOut/Moved, and more. When notified via a REST postback, developers can call into SharePoint and use various APIs to retrieve details on changed list items and documents. Over time, we expect to expand webhooks support to other types of events that happen inside of SharePoint.
Webhooks are also designed to be robust. They feature a built-in retry mechanism to enhance the reliability of message delivery, and webhooks make use of standard HTTP Status codes to determine how and when to retry requests.
SharePoint Add-ins support an existing notification mechanism known as remote event receivers. We will continue to support remote event receivers in addition to webhooks, so that developers can choose the technologies most relevant to them. While webhooks are fairly simple to use and feature robust retry logic, there are some use cases for event receivers: specifically, remote event receivers support synchronous events that occur as users update items.
We look forward to seeing what developers will build with webhooks, and we deeply value feedback from customers as we work towards general availability. If you have technical questions, please participate in the SharePoint Developer Community at https://aka.ms/spdevcommunity, or use the tag #spwebhooks on SharePoint StackExchange. Please let us know of any feature requests via SharePoint UserVoice. We’d love to see your work via @OfficeDev on Twitter.
