Usar webhooks para recibir notificaciones de servicio a servicio

Artículo
04/08/2023

OneDrive proporciona notificaciones entre servicios mediante webhooks. Los webhooks proporcionan una canalización simple de notificaciones, de modo que su aplicación pueda tener en cuenta los cambios de una unidad de usuario sin sondear el servicio.

Cuando los elementos a los que tiene acceso la aplicación en la unidad de un usuario se cambian, a la dirección URL que proporciona se le enviará una solicitud notificándole los cambios que se han producido.

Tareas comunes

Tarea	Método HTTP
Crear una suscripción	`POST /subscriptions`
Eliminar suscripción	`DELETE /subscriptions/{id}`
Actualizar una suscripción	`PATCH /subscriptions/{id}`

Registro

Para registrar webhooks, agregue una nueva suscripción al elemento que representa la parte superior del ámbito para el que quiere recibir cambios.

Vea agregar una suscripción nueva para obtener información sobre cómo registrar una dirección URL para las notificaciones.

Ámbito de notificaciones

Las notificaciones de webhooks se enviarán a la aplicación solo para los cambios que cumplan los siguientes criterios:

Un usuario ha autorizado que la aplicación tenga acceso a contenido de OneDrive.
La aplicación tiene acceso al elemento que genera la notificación.
La suscripción no ha expirado.

La aplicación no recibirá notificaciones para los elementos que se han compartido con el usuario que ha iniciado sesión o para los elementos remotos de la unidad del usuario a no ser que se creen suscripciones independientes en los elementos originales.

Recibir notificaciones

Una vez que se cree la suscripción, OneDrive enviará solicitudes POST a su dirección URL registrada cuando los elementos bajo el ámbito de notificación se cambien. Varias notificaciones de su servicio pueden agruparse por lotes conjuntamente en una sola solicitud, si varios usuarios tienen cambios que se producen dentro del mismo período de tiempo.

Ejemplo de notificación

El cuerpo de la solicitud HTTP para su dirección URL de notificación contendrá un recurso de notificación de webhook similar al siguiente:

{
  "value": [
    {
      "subscriptionId": "A640DFF3-0429-44FC-AF7E-30523A476864",
      "expirationDateTime": "2017-02-22T16:00:00Z",
      "resource": "/me/drive/root",
      "clientState": "client-specific string"
    }
  ]
}

Observará que la notificación no incluye ninguna información sobre los cambios que la han desencadenado. Se espera que la aplicación use el verbo delta para detectar cualquier cambio en el estado de los elementos de OneDrive y almacene el valor syncToken para la próxima vez que se le notifique.

Control de errores

Si se produce un error al enviar la notificación a su servicio, OneDrive seguirá la lógica de interrupción exponencial. Cualquier respuesta con un código de estado HTTP fuera del intervalo 200-299, o que agote el tiempo de espera, se intentará de nuevo en los próximos minutos. Si la solicitud no se realiza correctamente después de 15 minutos, se descarta la notificación.

Las notificaciones futuras se seguirán intentando en el servicio, aunque el servicio se reserve el derecho de quitar la suscripción si se detecta un número suficiente de errores.

Expiración

Se proporciona una fecha de expiración a las nuevas suscripciones automáticamente si no se proporciona una cuando se crea la suscripción. De manera predeterminada, las suscripciones se establecen para expirar en 6 meses desde la fecha en que se crearon.

Procedimientos recomendados

Cuando use webhooks, aquí se muestran algunas cosas importantes que tener en cuenta:

Entre servicios

No debe intentar usar webhooks para notificar a los dispositivos cliente directamente. Cada aplicación tiene una única URL de webhook que se llama para todos los usuarios. Esta URL debe indicar un servicio que controle. Puede decidir que su servicio analice los mensajes de notificación y reenvíe las notificaciones de inserción adecuadas a las aplicaciones cliente que quiera.

Responder rápidamente

La aplicación tiene un tiempo limitado para responder a la solicitud. Debe colocar en cola la información sobre las actualizaciones de notificación y, después, procesar esas solicitudes en un hilo separado. No debe intentar extraer los cambios desde el servicio de OneDrive antes de responder a la solicitud de webhook.

Esperar notificaciones simultáneas

En muchas circunstancias puede recibir notificaciones para el mismo usuario varias veces en una sucesión rápida. Por ejemplo, si un usuario es nuevo o está cargando un lote de contenido en OneDrive, puede recibir varias notificaciones para el mismo usuario antes de que haya procesado la primera notificación. Asegúrese de que las acciones que responden a notificaciones de webhooks controlan correctamente este caso.

Share via