Webhooks

Introducción

Los webhooks permiten notificar a un destinatario preconfigurado sobre eventos en el espacio de trabajo utilizando callbacks http/https. Un usuario puede configurar webhooks para que los eventos en el espacio de trabajo 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 Apps.

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

Creando un nuevo webhook

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

Una vez que crees y configures tu endpoint, puedes crear webhooks en el espacio de trabajo. 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 (Archivos, Salas, Formularios).

   nota

   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 del espacio de trabajo 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 espacio de trabajo.

   • 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 has perdido u olvidado esta clave secreta, abre la configuración del webhook y haz clic en el enlace Restablecer clave para generar una nueva. Todas las integraciones que usen el secreto anterior deberán actualizarse.

     

   • 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.

   • Evento que activa este webhook - 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 espacio de trabajo como Usuarios, Grupos, Archivos, Carpetas, Salas, Formularios y Agentes de IA. 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 del espacio de trabajo o solo al/los disparador/es seleccionado/s. Recibirás notificaciones automáticas sobre eventos del espacio de trabajo 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 del espacio de trabajo.

Gestionando webhooks

Los webhooks creados se muestran con su nombre, autor, URL de carga útil y estado. Puedes desactivar o volver a activar un webhook usando el interruptor en la columna Estado. Usa el icono a la derecha para abrir el menú contextual con las siguientes opciones:

• Configuración - cambia la configuración del webhook especificada durante su creación.
• Historial del webhook - consulta el historial de entregas del webhook.
• Eliminar webhook - elimina el webhook.

Haz clic en el webhook para ver el historial del 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.
• Tipo de evento – el evento 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.

Detalles técnicos

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 ONLYOFFICE Apps, por favor consulta api.onlyoffice.com.