Webhooks

Los webhooks permiten notificar a un destinatario preconfigurado sobre eventos en el portal utilizando callbacks http/https. Un usuario puede configurar webhooks para que los eventos en el portal desencadenen acciones en servicios externos. Este enfoque puede ser útil para sincronizar y rastrear ciertos eventos.

Utiliza webhooks para realizar acciones personalizadas en cualquier aplicación o sitio web que estés utilizando basadas en varios eventos en ONLYOFFICE DocSpace.

Puedes crear y gestionar todos tus webhooks, configurarlos y revisar el historial de cada webhook para auditar su rendimiento.

Primero, necesitas configurar un endpoint para los webhooks dentro de tu servicio externo. Este endpoint se usará para escuchar los webhooks de DocSpace y recibir notificaciones de eventos.

Una vez que crees y configures tu endpoint, puedes crear webhooks en DocSpace. Para crear un nuevo webhook,

1. Abre la sección Herramientas de Desarrollador haciendo clic en el enlace Herramientas de Desarrollador que está disponible en el panel izquierdo en cualquier sección (Salas, Documentos).
   Por defecto, el acceso a la sección Herramientas de Desarrollador está habilitado para todos los usuarios excepto invitados, de modo que cualquier usuario puede acceder a esta página y, en consecuencia, crear sus propios webhooks. Los administradores pueden ver todos los webhooks creados, mientras que los usuarios solo pueden ver sus propios webhooks.

   Los administradores pueden usar tanto el enlace Herramientas de Desarrollador en la izquierda como cambiar a esta sección desde la Configuración de DocSpace usando el menú en la esquina inferior izquierda, seleccionando la opción Configuración -> Herramientas de Desarrollador.

2. En Herramientas de Desarrollador, ve a la sección Webhooks.
3. Haz clic en el botón Crear webhook.
4. Establece los parámetros necesarios:
   
   • Nombre del webhook – un nombre identificador para trabajar de manera conveniente con el webhook en el portal.
   • URL de carga útil – una dirección del endpoint donde se debe enviar el webhook.
   • Clave secreta – establece una clave secreta del webhook que te permite verificar las solicitudes enviadas a la URL de carga útil. Ingresa tu propia clave o haz clic en Generar. Ten en cuenta: no podrás recuperar tu clave secreta una vez que se haya guardado. Si la pierdes u olvidas, puedes restablecerla, pero todas las integraciones que usen esta clave deberán ser actualizadas.
   • Verificación SSL – por defecto, esta opción está habilitada para verificar certificados SSL al entregar cargas útiles. No se recomienda desactivar este parámetro.
   • Disparador - utiliza la opción Enviar todo o marca el botón de radio Eventos individuales y elige solo los disparadores específicos, es decir, eventos sobre cambios en entidades del portal como Usuarios, Grupos, Documentos, Carpetas y Salas. Por ejemplo, usuario creado, invitado, actualizado, eliminado, etc.
   • ID de destino - un identificador de un usuario, un grupo, un archivo o una carpeta que te permite rastrear cambios de un objeto.
   
5. La URL de carga útil debe responder con el estado 200 a una solicitud http con el método HEAD.
6. Haz clic en el botón Crear.

Dependiendo de la configuración, el webhook creado se asignará a todos los eventos de DocSpace o solo al/los disparador/es seleccionado/s. Recibirás notificaciones automáticas sobre eventos de DocSpace dentro de tu servicio externo. Los disparadores seleccionados durante la creación de un webhook específico se activan solo si el propietario del webhook tiene derechos de acceso a la entidad modificada de DocSpace.

Puedes desactivar o volver a activar el webhook creado usando el interruptor junto a él. Usa el icono a la derecha para cambiar la configuración del webhook especificada durante su creación, ver el historial del webhook o eliminar el webhook.

Al ver el historial, puedes filtrar webhooks por fecha de entrega o estado (No enviado, 2XX, 3XX, 4XX, 5XX). Haz clic en el botón de filtro , elige los parámetros necesarios y haz clic en Aplicar.

Puedes seleccionar uno o más webhooks en la lista y usar la opción Reintentar que aparece en la parte superior para volver a entregar los webhooks seleccionados. O haz clic en el icono junto a un webhook determinado y selecciona la opción Reintentar en el menú contextual.

Haz clic en el icono junto a un webhook determinado y selecciona la opción Detalles del webhook en el menú contextual.

Los siguientes detalles están disponibles:

• Estado – un estado de respuesta.
• ID del evento – un ID del evento.
• Disparador – el disparador que causó que el webhook se activara.
• Hora del evento – una fecha en la que ocurrió el evento.
• Hora de entrega – una fecha en la que se recibió la respuesta del endpoint

En las secciones Solicitud/Respuesta, también puedes ver el encabezado de la solicitud POST, el cuerpo de la solicitud POST, el encabezado de la respuesta POST y el cuerpo de la respuesta POST. Usa el icono para copiar el encabezado o cuerpo de la solicitud/respuesta al portapapeles.

Usa el icono junto al título Detalles del webhook para volver a entregar el webhook.

Se utilizan los siguientes dos servicios para el trabajo:

1. ASC.Web.Studio proporciona métodos para enviar webhooks, lanza WorkerService.

   WorkerService – se suscribe para recibir mensajes de un broker (por ejemplo, RabbitMQ se utiliza por defecto), que almacena información sobre nuevos webhooks esperando ser enviados. Los mensajes recibidos del broker se colocan en una cola, después de lo cual la cola se consulta constantemente y se contacta de manera asincrónica con ASC.Webhoks.Service para enviar webhooks.

2. ASC.Webhooks.Core proporciona métodos para publicar webhooks en la base de datos y el broker de mensajes, así como métodos para trabajar con la base de datos.

Para más detalles sobre la API de DocSpace, por favor consulta api.onlyoffice.com.