WebHooks are user-defined HTTP callbacks. The problem they intend to solve is “pushing” information to you. Pushing is an unusually complex problem to solve. We’ve gotten so used to server-based applications, such as Office 365 resources, to expose a REST API that you “pull” information from.

Your application makes an HTTP call to find out if there is anything new. Pull works, but has some distinct disadvantages. It’s certainly not responsive enough for real-time operations, such as chat. And more importantly, it puts an undue load on both your application and the server.

 

 

Push, on the other hand would be nice, except, that Office 365 (or any server-based resource) doesn’t know where or who to push to. WebHook is an architectural pattern that aims to solve this issue.

Put simply, if you want SharePoint to inform you that a list has changed, you need to get an HTTP POST from Office365 to an endpoint that you expose. Before Office365 can send you a push, it needs to know where to send the push. A WebHook starts with subscribing to an endpoint where you express that you’re interested in learning about a specific notification, and that you’d like to be informed at such-and-such endpoint, which that server-based resource can push information or notifications to.

Before this subscription is considered valid, the server-based resource verifies that there’s an endpoint listening. And if an endpoint is indeed there, the subscription is created. In the future when the event occurs, this endpoint is called.

Of course, there are many other nuances to be considered, such as how long should such a notification subscription last? If the listener isn’t around to receive a push request, should there be any retry logic? How quickly should your endpoint respond? Should you send secure information in a push? How do you ensure that the server you created a subscription to is the one pushing the information?

Every platform implements things differently. In Office 365, the behavior is as follows:

  • The subscription lasts for a maximum of six months.
  • There is a retry logic built that retires every five minutes.
  • Your endpoint is expected to respond within five seconds. This time is intentionally short to reduce load on Office 365 server resources and prevent DDoS scenarios.
  • No secure information is sent and you’re expected to call back and get the nature of changes. The WebHook simply notifies you that “something has changed.” This is a good implementation because you want the WebHook to be responsive, and you can only make it responsive if the request size is predictable. Also, not sending sensitive information on a push notification is more secure.
  • You can be sure, as a recipient of a push, that the push came from who you subscribed to, by providing a validation code during your subscription. This validation code is your shared secret between Office 365 and your service.

 

Developers can get notified of events happening with SharePoint Lists, such as when items get added, updated, deleted or moved, now that the capability is now enabled in SharePoint Online.

As changes happen in SharePoint, calls are made to the developers’ service, and they can then react to those changes with code. We will continue to support remote event receivers in addition to webhooks, so that developers can choose the technologies most relevant to them.

How are WebHooks different? Well, there are some key differences.

  • WebHooks have an inbuilt retry mechanism. This means that if your endpoint was down when a change happened, the WebHook tries to deliver the message again. Remote event receivers, on the other hand, ran the real risk of losing your messages. They weren’t reliable.
  • WebHooks don’t call your endpoint immediately. Changes are batched, and the payload is small and predictable in size. There’s less risk of your endpoint getting an HTTP overflow or simply being too busy to respond to a lot of changes. It allows you to offload heavy lifting to a queue, etc.
  • WebHooks are more secure because no secure data is sent on the POST request. The actual request to get data is protected via standard SharePoint security.
  • WebHooks cannot be synchronous/real-time. They don’t allow cancel operations either.
  • WebHooks is an open standard. Remote event receivers were extremely specific to SharePoint. In fact, WebHooks are already available on non-SharePoint resources in Office 365. You can check out WebHooks in SharePoint, OneDrive, and Outlook.

In short, WebHooks are the future of eventing on the Office dev platform.

First, send a POST request to the specific list you intend to receive push notifications from. The POST request must be sent to a URL such as /_api/web/lists(‘list-id’)/subscriptions, and the payload looks like this:

 

The notificationUrl above is your way of saying: “If something happens to this list, please notify me at this URL.” Also note that you can’t specify an expiration date and time greater than six months. You could, of course, write logic that checks your subscriptions and automatically renews them as necessary.

Second, SharePoint Online responds back with an HTTP POST back to your notificationUrl. This reply looks like this:

https://someid.ngrok.io/api/spwebhook/handlerequest/?validationToken={randomString}

Third, note that there’s a validation token in this reply. This validation token is a GUID, and you’re expected to reply to the request with the validation token within five seconds.

Fourth, once SharePoint online receives this validation token, it responds with an HTTP 201 created message that looks like this:

 

At this time, your WebHook subscription is created.

 

Here are the detailed steps to be followed.

Step#1: Register Postman as an app to get the client ID and secret.

Callback URL would be https://www.getpostman.com/oauth2/callback 

1

Step#2: Make a note of the Application ID
2

Step#3: Grant required permissions
3

Step#4: Create a key(Client secret)
4

Step#5: Get the Library REST endpoint
5

Step#6:  Office365 should be able to reach your notificationURL, so run the website with ngrok
6

Step#7: In order to subscribe for the change notification,  you would also need access token.

  • https://login.microsoftonline.com/common/oauth2/authorize?resource=https%3A%2F%2Fspblog.sharepoint.com
  • https://login.microsoftonline.com/common/oauth2/token

7

8

Once the access token is created, click on the “Preview” button to add it on the request.

Step#8: Now you can subscribe for the notification
9

Step#9: Upload a document on the document library and validate.

 

Finally here is the MVC code is used to handle the request.

 

Reference: http://www.codemag.com/article/1707031