Información general de los webhooks de SharePoint

Artículo
04/08/2023

Los webhooks de SharePoint permiten que los desarrolladores creen aplicaciones que se suscriban para recibir notificaciones sobre eventos determinados que se produzcan en SharePoint. Cuando se desencadena un evento, SharePoint envía una carga HTTP POST al suscriptor. Los webhooks son más fáciles de desarrollar y consumir que los servicios de Windows Communication Foundation (WCF) que usan los receptores de eventos remotos de complementos de SharePoint, ya que los webhooks son servicios HTTP normales (API web).

Actualmente, los webhooks solo se habilitan para elementos de lista de SharePoint. Los webhooks del elemento de la lista de SharePoint cubren los eventos que se corresponden con los cambios de elemento de lista de una lista de SharePoint determinada o una biblioteca de documentos. Los webhooks de SharePoint proporcionan una canalización simple de notificaciones, de modo que su aplicación pueda tener en cuenta los cambios de una lista de SharePoint sin sondear el servicio. Para obtener más información, vea Webhooks de lista de SharePoint.

Crear webhooks

Para crear un nuevo webhook de SharePoint, agregue una nueva suscripción al recurso de SharePoint determinado, como una lista de SharePoint.

La siguiente información se necesita para crear una suscripción nueva:

Recurso. Dirección URL del punto de conexión de recurso para la que va a crear la suscripción. Por ejemplo, una dirección URL de API de lista de SharePoint.
Dirección URL de notificación del servidor. La dirección URL del punto de conexión de servicio. SharePoint envía un método HTTP POST a este punto de conexión cuando se producen eventos en el recurso especificado.
Fecha de expiración. La fecha de expiración de su suscripción. La fecha de expiración no debe ser superior a 180 días. De manera predeterminada, las suscripciones se establecen para expirar en 180 días desde la fecha en que se crearon.

También puede incluir la siguiente información si fuera necesario:

Estado del cliente. Una cadena opaca que se ha pasado al cliente en todas las notificaciones. Puede usarla para validar las notificaciones, etiquetar suscripciones diferentes o por otros motivos.

Controlar las solicitudes de validación de webhooks

Cuando se crea una suscripción, SharePoint valida si la dirección URL de notificación admite la recepción de notificaciones de webhook. Esta validación se realiza durante la solicitud de creación de la suscripción. La suscripción solo se crea si su servicio responde en el tiempo esperado con el token de validación.

Ejemplo de solicitud de validación

Cuando se crea una suscripción, SharePoint envía una solicitud HTTP POST a la dirección URL registrada en un formato similar al del ejemplo siguiente:

POST https://contoso.azurewebsites.net/your/webhook/service?validationtoken={randomString}
Content-Length: 0

Respuesta

Para que la suscripción se cree correctamente, su servicio debe responder a la solicitud devolviendo el valor del parámetro de la cadena de consulta validationToken como una respuesta de texto sin formato.

HTTP/1.1 200 OK
Content-Type: text/plain

{randomString}

Si su aplicación devuelve un código de estado diferente a 200 o se produce un fallo al responder con el valor del parámetro validationToken, se produce un error en la solicitud que va a crear una suscripción.

Recibir notificaciones

La carga de notificación informa a su aplicación de que se ha producido un evento en un recurso determinado para una suscripción dada. Varias notificaciones de su aplicación pueden agruparse por lotes conjuntamente en una sola solicitud, si se han producido varios cambios en el recurso dentro del mismo período de tiempo.

El cuerpo de la carga de notificación también contiene su estado de cliente si lo ha usado al crear la suscripción.

Recurso de notificación de webhook

El recurso de notificación define la forma de los datos que se han proporcionado en su servicio cuando se presenta una solicitud de notificación de webhook de SharePoint en su dirección URL de notificación registrada.

Representación JSON

Cada notificación que ha generado el servicio se serializa en una instancia webhookNotification:

{
    "subscriptionId":"91779246-afe9-4525-b122-6c199ae89211",
    "clientState":"00000000-0000-0000-0000-000000000000",
    "expirationDateTime":"2016-04-30T17:27:00.0000000Z",
    "resource":"b9f6f714-9df8-470b-b22e-653855e1c181",
    "tenantId":"00000000-0000-0000-0000-000000000000",
    "siteUrl":"/",
    "webId":"dbc5a806-e4d4-46e5-951c-6344d70b62fa"
}

Como pueden enviarse varias notificaciones a su servicio en una sola solicitud, estas se combinan conjuntamente en un objeto con un valor individual de matriz:

{
   "value":[
      {
         "subscriptionId":"91779246-afe9-4525-b122-6c199ae89211",
         "clientState":"00000000-0000-0000-0000-000000000000",
         "expirationDateTime":"2016-04-30T17:27:00.0000000Z",
         "resource":"b9f6f714-9df8-470b-b22e-653855e1c181",
         "tenantId":"00000000-0000-0000-0000-000000000000",
         "siteUrl":"/",
         "webId":"dbc5a806-e4d4-46e5-951c-6344d70b62fa"
      }
   ]
}

Propiedades

Nombre de la propiedad	Tipo	Descripción
resource	String	Identificador único de la lista donde se ha registrado la suscripción.
subscriptionId	String	El identificador único del recurso de la suscripción.
clientState	String: opcional	Un valor de cadena opcional que se pasa al mensaje de notificación de esta suscripción.
expirationDateTime	DateTime	La fecha y la hora en que expira la suscripción si no la ha actualizado o renovado.
tenantId	String	Identificador único del espacio empresarial que ha generado esta notificación.
siteUrl	String	Dirección URL relativa al servidor del sitio donde se ha registrado la suscripción.
webId	String	Identificador único de la web donde se ha registrado la suscripción.

Ejemplo de notificación

El cuerpo de la solicitud HTTP para su dirección URL de notificación del servicio contiene una notificación de webhook. En el siguiente ejemplo se muestra una carga con una notificación:

{
   "value":[
      {
         "subscriptionId":"91779246-afe9-4525-b122-6c199ae89211",
         "clientState":"00000000-0000-0000-0000-000000000000",
         "expirationDateTime":"2016-04-30T17:27:00.0000000Z",
         "resource":"b9f6f714-9df8-470b-b22e-653855e1c181",
         "tenantId":"00000000-0000-0000-0000-000000000000",
         "siteUrl":"/",
         "webId":"dbc5a806-e4d4-46e5-951c-6344d70b62fa"
      }
   ]
}

La notificación no incluye ninguna información sobre los cambios que la han desencadenado. Se espera que la aplicación use GetChanges API en la lista para consultar la recopilación de cambios del registro de cambios y almacene el valor del token de cambio de cualquier llamada posterior cuando se notifique la aplicación.

Tipos de eventos

Los webhooks de SharePoint solo admiten eventos asincrónicos. Esto significa que los webhooks solo se desencadenan después de que se produzca un cambio (similar a los eventos -ed) y, por lo tanto, los sincrónicos (eventos -ing) no son posibles.

Control de errores

Si se produce un error al enviar la notificación a su aplicación, SharePoint intenta enviar la notificación hasta cinco veces. Cualquier respuesta con un código de estado HTTP fuera del intervalo 200-299, o que agote el tiempo de espera, se intenta de nuevo cinco minutos más tarde. Si la solicitud no se realiza correctamente después de cinco intentos, se descarta la notificación. Las notificaciones futuras se seguirán intentando en la aplicación.

Expiración

Las suscripciones de webhook se establecen para expirar después de 180 días de manera predeterminada si no se especifica un valor expirationDateTime.

Necesita establecer una fecha de expiración al crear la suscripción. La fecha de expiración debe ser inferior a 180 días. Se espera que la aplicación controle la fecha de expiración según las necesidades de su aplicación actualizando la suscripción periódicamente.

Mecanismo de reintento

Si se produce un evento en SharePoint y su punto de conexión de servicio no está accesible (por ejemplo, debido al mantenimiento), SharePoint vuelve a intentar enviar la notificación. SharePoint realiza un reintento de cinco veces con un tiempo de espera de cinco minutos entre los intentos. Si por algún motivo su servicio está inactivo durante un período de tiempo superior, la próxima vez que esté activo y SharePoint lo llame, la llamada a GetChanges() recupera los cambios que faltaban cuando su servicio no estaba disponible.

Compartir a través de