Información general de los webhooks de SharePointOverview of SharePoint webhooks

Los webhooks de SharePoint permiten que los desarrolladores creen aplicaciones que se suscriban para recibir notificaciones sobre eventos determinados que se produzcan en SharePoint.SharePoint webhooks enable developers to build applications that subscribe to receive notifications on specific events that occur in SharePoint. Cuando se desencadena un evento, SharePoint envía una carga HTTP POST al suscriptor.When an event is triggered, SharePoint sends an HTTP POST payload to the subscriber. 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).Webhooks are easier to develop and consume than Windows Communication Foundation (WCF) services used by SharePoint Add-in remote event receivers because webhooks are regular HTTP services (web API).

Actualmente, los webhooks solo se habilitan para elementos de lista de SharePoint.Currently webhooks are only enabled for SharePoint list items. 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.SharePoint list item webhooks cover the events corresponding to list item changes for a given SharePoint list or a document library. 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.SharePoint webhooks provide a simple notification pipeline so that your application can be aware of changes to a SharePoint list without polling the service. Para obtener más información, vea Webhooks de lista de SharePoint.For more information, see SharePoint list webhooks.

Crear webhooksCreating webhooks

Para crear un nuevo webhook de SharePoint, agregue una nueva suscripción al recurso de SharePoint determinado, como una lista de SharePoint.To create a new SharePoint webhook, you add a new subscription to the specific SharePoint resource, such as a SharePoint list.

La siguiente información se necesita para crear una suscripción nueva:The following information is required for creating a new subscription:

  • Recurso. La dirección URL del punto de conexión del recurso para el que está creando la suscripción. Por ejemplo, una dirección URL de la API de lista de SharePoint.Resource. The resource endpoint URL you are creating the subscription for. For example, a SharePoint List API URL.
  • Dirección URL de notificación del servidor.Server notification URL. La dirección URL del punto de conexión de servicio.Your service endpoint URL. SharePoint envía un método HTTP POST a este punto de conexión cuando se producen eventos en el recurso especificado. SharePoint sends an HTTP POST to this endpoint when events occur in the specified resource.
  • Fecha de expiración.Expiration date. La fecha de expiración de su suscripción.The expiration date for your subscription. La fecha de expiración no debe ser superior a 180 días.The expiration date should not be more than 180 days. De manera predeterminada, las suscripciones se establecen para expirar en 180 días desde la fecha en que se crearon.By default, subscriptions are set to expire 180 days from when they are created.

También puede incluir la siguiente información si fuera necesario:You can also include the following information if needed:

  • Estado del cliente.Client State. Una cadena opaca que se ha pasado al cliente en todas las notificaciones.An opaque string passed back to the client on all notifications. Puede usarla para validar las notificaciones, etiquetar suscripciones diferentes o por otros motivos.You can use this for validating notifications, tagging different subscriptions, or other reasons.

Controlar las solicitudes de validación de webhooksHandling webhook validation requests

Cuando se crea una suscripción, SharePoint valida si la dirección URL de notificación admite la recepción de notificaciones de webhook.When a new subscription is created, SharePoint validates whether the notification URL supports receiving webhook notifications. Esta validación se realiza durante la solicitud de creación de la suscripción.This validation is performed during the subscription creation request. La suscripción solo se crea si su servicio responde en el tiempo esperado con el token de validación.The subscription is only created if your service responds in a timely manner back with the validation token.

Ejemplo de solicitud de validaciónExample validation request

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:When a new subscription is created, SharePoint sends an HTTP POST request to the registered URL in a format similar to the following example:

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

RespuestaResponse

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.For the subscription to be created successfully, your service must respond to the request by returning the value of the validationtoken query string parameter as a plain-text response.

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.If your application returns a status code other than 200, or fails to respond with the value of the validationtoken parameter, the request to create a new subscription fails.

Recibir notificacionesReceiving notifications

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.The notification payload informs your application that an event occurred in a given resource for a given subscription. 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.Multiple notifications to your application may be batched together into a single request if multiple changes occurred in the resource within the same time period.

El cuerpo de la carga de notificación también contiene su estado de cliente si lo ha usado al crear la suscripción.The notification payload body also contains your client state if you used it when creating the subscription.

Recurso de notificación de webhookWebhook notification resource

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.The notification resource defines the shape of the data provided to your service when a SharePoint webhook notification request is submitted to your registered notification URL.

Representación JSONJSON representation

Cada notificación que ha generado el servicio se serializa en una instancia webhookNotification:Each notification generated by the service is serialized into a webhookNotification instance:

{
    "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:Because multiple notifications may be submitted to your service in a single request, these are combined together in an object with a single array value:

{
   "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"
      }
   ]
}

PropiedadesProperties

Nombre de la propiedadProperty name TipoType DescripciónDescription
resourceresource StringString Identificador único de la lista donde se ha registrado la suscripción.Unique identifier of the list where the subscription is registered.
subscriptionIdsubscriptionId StringString El identificador único del recurso de la suscripción.The unique identifier for the subscription resource.
clientStateclientState String: opcionalString - optional Un valor de cadena opcional que se pasa al mensaje deAn optional string value that is passed back in the notification. notificación de esta suscripción.message for this subscription.
expirationDateTimeexpirationDateTime DateTimeDateTime La fecha y la hora en que expira la suscripción si no la ha actualizado o renovado.The date and time when the subscription expires if not updated or renewed.
tenantIdtenantId StringString Identificador único del espacio empresarial que ha generado esta notificación.Unique identifier for the tenant that generated this notification.
siteUrlsiteUrl StringString Dirección URL relativa al servidor del sitio donde se ha registrado la suscripción.Server relative URL of the site where the subscription is registered.
webIdwebId StringString Identificador único de la web donde se ha registrado la suscripción.Unique identifier of the web where the subscription is registered.

Ejemplo de notificaciónExample notification

El cuerpo de la solicitud HTTP para su dirección URL de notificación del servicio contiene una notificación de webhook.The body of the HTTP request to your service notification URL contains a webhook notification. En el siguiente ejemplo se muestra una carga con una notificación:The following example shows a payload with one notification:

{
   "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.The notification doesn't include any information about the changes that triggered it. Your application is expected to use the GetChanges API on the list to query the collection of changes from the change log and store the change token value for any subsequent calls when the application is notified.

Tipos de eventosEvent types

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.SharePoint webhooks only support asynchronous events. This means that webhooks are only fired after a change happened (similar to -ed events), and thus synchronous (-ing events) are not possible.

Control de erroresError handling

Si se produce un error al enviar la notificación a su aplicación, SharePoint intenta enviar la notificación hasta cinco veces.If an error occurs while sending the notification to your application, SharePoint retries up to 5 times to deliver the notification. 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.Any response with an HTTP status code outside of the 200-299 range, or that times out, is attempted again 5 minutes later. Si la solicitud no se realiza correctamente después de cinco intentos, se descarta la notificación.If the request is not successful after 5 attempts, the notification is dropped. Las notificaciones futuras se seguirán intentando en la aplicación.Future notifications will still be attempted to your application.

ExpiraciónExpiration

Las suscripciones de webhook se establecen para expirar después de 180 días de manera predeterminada si no se especifica un valor expirationDateTime.Webhook subscriptions are set to expire after 180 days by default if an expirationDateTime value is not specified.

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.You need to set an expiration date when creating the subscription. The expiration date should be less than 180 days. Your application is expected to handle the expiration date according to your application's needs by updating the subscription periodically.

Mecanismo de reintentoRetry mechanism

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.If an event occurs in SharePoint and your service endpoint is not reachable (for example, due to maintenance) SharePoint retries sending the notification. SharePoint realiza un reintento de cinco veces con un tiempo de espera de cinco minutos entre los intentos.SharePoint performs a retry of 5 times with a 5-minute wait time between the attempts. 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.If for some reason your service is down for a longer time, the next time it's up and gets called by SharePoint, the call to the GetChanges() recovers the changes that were missed when your service was not available.