Introduction To Office 365 Webhooks And Connectors

In this article, I will explain about Webhooks and Connectors and how we can use them in Office 365.

We know that users need access to information and in Office 365, users can get access to information either through Office 365 or through other Line-of-Business (LOB) applications. These applications might have been provided by vendors or these might be your custom applications which you are writing.

Connectors allow these applications (either 3^rd party or written by you) to publish information within Office 365. Webhooks allow third party applications to express that they are interested to learn about some specific events, and that Office 365 should notify them when those events occur.

Both connectors and webhooks are established on well-established standards. These are basically HTTP-POST based calls. Now the question is where does the information surface in Office 365 and how do users express their interest in certain kinds of information.

So, let’s start with a basic understanding of how connectors work in Office 365.

Connectors in Office 365

The below diagram shows the complete functionality of Connectors in Office 365,

1. It starts with a user expressing interest in a certain channel or a connector of information. These connectors need to be registered in Office 365 so that users can pick one of those connectors.
   
   
2. The connector can present a custom user interface, which means the user can configure the connector. The user interface is specific to the connector.
   
   
3. Once the user has gone through the configuration process, a connector is registered. Technically, it means that a URL is given to the connector and now the connector can issue POST messages in a specific schema to that URL.
   
   
4. If the connector issues a POST request matching that schema to that particular URL, that information becomes available in Office 365.
   
   
5. This information which is available in Office 365 can be viewed by the users.
   
   
6. Users have the option of removing or reconfiguring these connectors. Once removed the URL will no longer be valid and the POST requests will no longer work.

Webhooks in Office 365

The below diagram shows the complete functionality of Webhooks in Office 365,

• Your application requests for a subscription. In other words, your application expresses interest in Office 365 that it is entrusted with knowing about certain kinds of events.
  
  
• In that subscription request, your application would need to provide Office 365 with an internet callable URL and you must confirm that URL.
  
  
• The way you confirm that URL is that Office 365 will issue a call that you have to reply to within 5 seconds and that is why that URL must be exposed to the internet because Office 365 needs to be able to call that URL without having to worry about firewalls.
  
  
• Now once this subscription is set up, you are now listening to those notifications, and as long as you have that web service exposed Office 365 can call.
  
  
• Now if a change occurs, for example a new document is uploaded in the document library where the subscription is configured, you will not be informed that a change has occurred.
  
  
• About every 5 minutes, Office 365 will alert all entrusted parties; however, all of those entrusted parties are not given the details of the change. So, the actual details of the change are not part of the notification, you still have to call back into Office 365 to see what happened. This is a very good design pattern for two reasons:- a) The POST request, the alert coming from Office 365 is secure because it has nothing in it. b) It is always off of predictable sites. So, your web service has a very cheap request to serve and then you can put the processing in a queue.
  
  
• There are APIs available that allow you to iterate through existing subscriptions, those are managed subscriptions or even delete existing subscriptions.
  
  
• These subscriptions have a finite life of 6 months currently in Office 365. In other words, when you subscribe or set up a subscription, the maximum duration you can set up the subscription is for six months.

Webhook is an HTTP call-back (POST to a certain URL, when an event occurs in Office 365), usually triggered by some event that you subscribe to. Webhooks are not limited to Office 365, however, Office 365 has chosen to implement Webhooks.

For Office 365 to be able to make a call-back to you, it needs to know what URL it is supposed to make a call-back to. And you would communicate that URL to Office 365 when you express that interest. So, that URL also needs to be on the open internet. In other words, this URL needs to be accessible without any firewalls etc.

Webhooks vs Remote Event Receivers

How do webhooks compare with Remote event receivers and why did Microsoft choose to create yet another eventing model?

An event receiver is fire and forget. If your listening endpoint was down, you will miss that message. Webhooks, on the other hand, are a lot more robust. They have a retry mechanism. Webhooks are the open standard (not invented by Microsoft).

Remote event receivers also choose to send all the details with the notification, so they are less secure as compared to Webhooks. Webhooks are more scalable too. They are scalable from an Office 365 point of view because subscriptions can grow infinitely and you must respond within 5 seconds.

Remote event receivers can be synchronous or asynchronous, however, Webhooks are asynchronous.

Currently, webhooks are available on SharePoint, OneDrive and Outlook.

Summary

In this article, I tried to explain Webhooks in very simple terms. Webhooks are the future of eventing in SharePoint and Office 365.