Los webhooks proporciona un mecanismo con el que implementar un sistema de eventos asíncronos en SharePoint basado en suscripciones, a través del cual podremos ejecutar acciones sobre eventos realizados sobre los elementos de una lista desde un proceso seguro y con un control de reintentos. Aunque todavía se encuentra en preview, será un sistema alternativo a los RemoteEventReceivers.

A nivel de concepto, los webhooks permiten ejecutar código desde un proceso externo a SharePoint Online ante un evento producido en una lista. Para capturar los eventos implementaremos un servicio REST que será el encargado de ejecutar todos los eventos e interactuar con SharePoint a través de CSOM.

Registro de una suscripción

Para registrar un Webhook tendremos que realizar una suscripción sobre la lista a través del servicio REST «suscriptions» (/_api/web/lists(‘list-id’)/subscriptions) al que indicaremos:

  • La url de la lista sobre la que deseamos registrar el webhook.
  • La url de nuestros servicio REST que capturará los eventos.
  • La fecha de expiración de la suscripción que estamos registrando.
  • Y opcionalmente, una cadena de validación que utilizaremos en todas las llamadas para validar las llamadas a nuestro servicio REST.

Una vez realizada la suscripción, se realizará un proceso de comprobación de disponibilidad del servicio, de manera que el servicio de suscripción de webhook realizará una llamada a nuestro servicio REST con un token, «validationtoken», que debemos devolver para confirmar la suscripción. En caso que nuestro servicio no devuelva este token o tarde más de 5 segundos se cancelará automáticamente la suscripción.

La suscripción de un webhook tiene una caducidad máxima de 6 meses, por lo que tendremos que implementar in mecanismo de renovación que asegure la asociación del webhook.

El servicio «subscription» proporciona las siguientes operaciones:

Task HTTP method
Create a new subscription POST /_api/web/lists(‘list-guid’)/subscriptions
Get subscriptions GET /_api/web/lists(‘list-guid’)/subscriptions
Delete a subscription DELETE /_api/web/lists(‘list-guid’)/subscriptions(‘id’)
Update a subscription PATCH /_api/web/lists(‘list-guid’)/subscriptions(‘id’)

Para realizar una llamada al servicio de suscripción requerirá de un token «bearer» que debemos obtener registrando nuestro servicio como un Addin de SharePoint. Si estamos utilizando Windows Azure tendremos que dar el siguiente permiso a nuestra aplicación:

Application Permission
Office 365 SharePoint Online Read and write items and lists in all site collections.

Capturando un evento

Todos los eventos son asíncronos y sobre acciones ya ejecutadas en un elemento (en pasado) de una lista de SharePoint. No se disponen de métodos síncronos sobre los que poder actuar para cancelar una acción, como pudieran tener los Remote events. Actualmente se pueden capturar de los siguientes eventos:

  • ItemAdded
  • ItemUpdated
  • ItemDeleted
  • ItemCheckedOut
  • ItemCheckedIn
  • ItemUncheckedOut
  • ItemAttachmentAdded
  • ItemAtttachmentDeleted
  • ItemFileMoved
  • ItemVersonDeleted
  • ItemFileConverted

Al producirse un evento, el webhook realizará una llamada a nuestro servicio REST para que lo procese gestionando en nuestro código el tipo de acción o estado producido.

Se realizará una llamada a nuestro servicio haciendo POST con un array de uno o varios elementos «value» con los siguientes valores:

  • Identificador de la lista a la que nos hemos suscrito.
  • Identificador de la suscripción
  • Fecha de expiración de la suscripción para realizar una renovación
  • Identificador del tenant
  • URL de la colección
  • Url del sitio web

Nuestro servicio tendrá que contestar en un tiempo máximo de 5 segundos y con un código de resultado 200. En caso de producirse un error el web hook realizará un proceso de reintentos de hasta 5 reintentos cada 5 minutos.

El webhook no realizará una llamada a nuestro servicio por cada evento producido, ya que esta operación no se ejecutará inmediatamente debido a que el webhook encolará los eventos y los procesará en batch en un período de tiempo de un minuto. Al procesar la llamada en caso de encontrarse con varios eventos, en lugar de realizar múltiples llamadas a nuestro servicio por cada ejecución, realizará una sola llamada a nuestro servicio, devolviendo un array de valores de llamada.

De modo que tendremos que encargarnos de controlar todos los cambios realizados desde la última ejecución de nuestro servicio REST. Utilizaremos el API GetChanges con el que seremos capaces de obtener todas las diferencias realizadas a partir de un cierto momento.

Implementación sobre Windows Azure

La forma más sencilla de implementar un Webhook para SharePoint Online será utilizar Windows Azure, con el que podremos desplegar nuestro servicio REST y utilizar WebJobs para renovar la suscripciones o procesar las peticiones.

En github disponemos del proyecto Webhook.List con el que encontraremos un ejemplo de imeplementación de Webhook sobre Windows Azure.

En este sentido disponemos de varias aproximaciones, pero para una implementación donde esperamos un gran volumen de datos requeriremos de apoyarnos de otros servicios que nos permitan un procesamiento en background de nuestro evento y devuelva un código 200 al webhook. Un ejemplo sería utilizar una cola de Windows Azure para almacenar las peticiones recibidas por nuestro servicio para ser procesadas posteriormente por un WebJob.

Recursos: