Presentación

En Docebo puedes crear webhooks para que se desencadenen cuando se produzca un evento en tu plataforma, enviándote información sobre dicho evento a una URL de carga útil específica. Esto te permite recopilar datos de tu plataforma de aprendizaje para crear informes, integraciones, paneles de control y más. También puedes, por ejemplo, conectarte a tu sistema de gestión del capital humano (HCM), enviar un correo electrónico a usuarios que no sean de Docebo Learn sobre acciones que se produzcan dentro de la plataforma o actualizar la gestión del almacenamiento de tu contenido.

Cuando hayas activado la aplicación Webhooks en tu plataforma, puedes crear una entrada de un evento inicial, Docebo coloca los datos relacionados con ese evento en un mensaje JSON y lo envía a través de una llamada HTTP o HTTPS POST (no a través de correo electrónico o notificaciones) a una URL determinada que hayas configurado para el webhook emparejado con ese evento.

También puedes crear webhooks a través del conjunto completo de APIs de webhook proporcionadas por Docebo. Consulta la documentación de la API oficial para obtener más información. Ten en cuenta que la funcionalidad del webhook se ampliará con el tiempo para incluir varias integraciones y eventos adicionales. Consulta la página Actualizaciones del producto para obtener más información.

Este artículo describe cómo activar la aplicación Webhooks, cómo crear y gestionar webhooks, información para cargas útiles y aceleradores y otras notas importantes que necesitas saber para usar webhooks en tu plataforma. Para ver ejemplos de webhooks, eventos para incluir en tus webhooks y descripciones JSON para cada evento, consulta Eventos Webhooks para obtener más información.

Información importante

• La aplicación Webhooks solo está disponible para clientes Enterprise.
• Esta aplicación solo puede ser gestionada por Superadministradores. Los Usuarios avanzados no tienen permisos para ver o gestionar webhooks.

Activación de la aplicación

Activa la aplicación Webhooks como se describe en el artículo Gestionar aplicaciones y características de la Base de conocimiento. La aplicación aparece relacionada en la pestaña Características adicionales de Docebo.

Creación de webhooks

Una vez activada la aplicación, puedes gestionarla accediendo al Menú Admin y pulsando el elemento Gestionar de la sección Webhooks. En la página principal de Webhooks puedes agregar y gestionar todos tus webhooks, habilitarlos o deshabilitarlos, editarlos o eliminarlos y comprobar los errores externos del sistema (en su caso).

Para añadir un webhook, pulsa el botón más de la esquina superior derecha de la página. En la página de configuración, comienza en la sección General. Agrega un nombre para tu webhook; puede ser cualquier nombre identificable de tu elección, pues solo se utiliza internamente en tu plataforma. A continuación, añade la URL de la carga útil a la que se enviará la información del webhook.

En la sección Eventos, pulsa el botón Seleccionar eventos para añadir eventos al webhook. En el panel deslizante, marca hasta ocho eventos para incluirlos en el webhook y a continuación, pulsa Confirmar. Después verás que el campo Eventos se rellena con los eventos seleccionados. Puedes eliminar los eventos en cualquier momento utilizando el icono X que hay junto a cada uno. Puedes encontrar más detalles sobre cada webhook y los códigos JSON correspondientes en el artículo Eventos Webhooks.

En la sección Autenticación puedes cambiar la opción a Habilitar autenticación básica para tu extremo de recepción. Si se habilita, tendrás que insertar tu nombre de usuario y contraseña de autenticación básica en los campos correspondientes de la sección Información del protocolo.

La sección Colección de carga útil es donde se puedes definir si se deben agrupar en una sola entrega de mensajes las cargas útiles relacionadas con eventos del mismo tipo y generados por el mismo proceso. Por ejemplo, cuando está habilitada esta opción, si un webhook incluye el evento Curso creado y una sola llamada API crea diez cursos en la plataforma, el extremo recibirá un solo webhook que incluye diez eventos Curso creado, en lugar de recibir diez mensajes webhook separados, uno por cada nuevo curso.

Ten en cuenta que habilitar esta opción no garantiza que el número de eventos incluidos en una colección de carga útil corresponda al número de eventos generados por el proceso desencadenante (la llamada API en nuestro ejemplo). El número de eventos coleccionados en webhooks cambia dependiendo de la lógica de optimización del búfer de la infraestructura de la plataforma. Volviendo a nuestro ejemplo, cuando la llamada API desencadena la creación de diez cursos, dependiendo de la lógica de optimización del búfer, es posible que recibas un webhook que incluya una colección de diez eventos, dos webhooks que incluyan ocho eventos cada uno o un webhook que recopile nueve eventos más un webhook de un solo evento.

Cuando los webhooks incluyen más de un evento, la carga útil de propiedad común del webhook se convierte en cargas útiles, lo que indica que el mensaje incluye más eventos. Si habilitas la función de colección de carga útil, asegúrate de que el sistema de tu extremo esté listo para recibir webhooks con dos estructuras diferentes.

Cuando hayas terminado de configurar tu nuevo webhook, pulsa el botón Guardar cambios para crearlo. El nuevo webhook se mostrará en la lista de la página principal de Webhooks y estará desactivado de forma predeterminada. Consulta las secciones correspondientes siguientes para saber cómo deshabilitar, volver a habilitar, editar o eliminar tus webhooks.

Notas sobre la creación de webhooks

• La URL de carga útil debe tener el formato correcto de HTTP o HTTPS. Puedes insertar una URL de carga útil por webhook, y puedes añadir hasta ocho eventos por webhook, por lo que puedes enviar información para más de un evento a esta URL de carga útil única.
• Si bien no hay límite en la cantidad de webhooks que crees o configures, por razones de rendimiento, en cualquier momento puedes tener hasta un máximo de diez webhooks habilitados en tu plataforma. Cada webhook puede tener un máximo de ocho eventos por webhook. Ten esto en cuenta al crear y habilitar tus webhooks.
• Docebo recomienda encarecidamente usar HTTPS y habilitar la autenticación básica cuando se usan webhooks, pues añade seguridad a la información que la plataforma envíe a tu extremo.
• Cuando se trate de rotación de autenticación básica y contraseña, asegúrate de permitir que la contraseña antigua siga siendo válida durante algún tiempo, dependiendo de tu tráfico. Los mensajes antiguos se autenticarán usando las contraseñas antiguas; si ya no las aceptas, esos mensajes fracasarán.
• Realiza siempre un seguimiento de los correos electrónicos de notificación de errores de entrega. Si un solo mensaje no se entrega durante un periodo de 60 horas, el sistema desactivará el webhook. Esto significa que este webhook no enviará ningún mensaje nuevo. Se entregarán los mensajes enviados antes de que se desactivara el webhook que aún estén en la cola.
• Separa tus webhooks en diferentes dominios (domain1.webhook.com, domain2.webhook.com, etc.) para garantizar que los webhooks para tu plataforma se gestionen mediante colas paralelas si esperas una alta tasa de mensajes. Esto no es necesario para un tráfico bajo, pero agruparlos en diferentes colas puede optimizar los tiempos de entrega.

Cargas útiles de webhooks

Habilitar datos adicionales para la carga útil

Dependiendo de tus necesidades, es posible que quieras activar datos adicionales para la carga útil, de forma que la información que se transmita a sistemas externos sea más detallada. Hay datos adicionales disponibles para cursos, seminarios web, inscripciones y planes de aprendizaje. Si estás interesado/a en activar datos adicionales, ponte en contacto con el servicio de ayuda a través del Centro de ayuda.

La sección de datos adicionales de la carga útil se identifica como extra_data.

Notas sobre las cargas útiles de webhooks

• Ten en cuenta que por razones de rendimiento, las cargas útiles de Docebo son cargas útiles delgadas, lo que significa que proporcionan información básica a tu URL de carga útil. Si quieres más información, debes consultar directamente la carga útil. Puedes identificar el ID de los recursos actualizados a través del webhook y a continuación, volver a llamar a la API adecuada para las actualizaciones.
• Las cargas útiles de webhooks siempre incluyen un parámetro de identificación que tiene 56 caracteres de longitud.
• Identifica qué eventos de webhooks pueden ocurrir después de acciones por lotes y habilita cargas útiles agrupadas en ellos. Cuando Docebo Learn realiza una acción intensiva que desencadena varios eventos del mismo tipo en un período de tiempo muy corto, el webhook enviado puede contener varias cargas útiles del mismo tipo de evento en un mensaje. Esto garantiza que haya menos mensajes para entregar, lo que te brinda la capacidad de consumir más eventos a una tasa más alta.

Cómo responder a los webhooks

Para confirmar la recepción de un webhook, Docebo espera que se devuelva un código de estado HTTP 2xx o 3xx. La recepción de un código de estado de error 4xx o 5xx dará como resultado que el envío se registre como un error. Ten en cuenta también que si Docebo no recibe una respuesta dentro de los 5 segundos posteriores al envío de la solicitud, esta se considera un error y se registra como tal, incluso si el servidor remoto pueda estar procesando la solicitud pero simplemente no ha respondido a tiempo. Consulta el artículo Gestión de errores para obtener más información.

Notas sobre la respuesta a webhooks

• Trata de responder con un mensaje 200 en el menor tiempo posible. El sistema de entrega de webhook tiene un tiempo de espera de 5 segundos, tras el cual considera la entrega como fallida y desencadena una reprogramación. Si no devuelves un mensaje 200, Docebo no puede verificar que has recibido el webhook.
• En el extremo receptor, una buena práctica es almacenar los webhooks primero, acusar recibo en segundo lugar y por último, procesarlos. Dado que, por naturaleza, los webhooks se pueden enviar en varios órdenes (no necesariamente cronológicos) y se pueden enviar varias veces por problemas de entrega, almacenarlos y procesarlos más tarde te permite filtrar los mensajes duplicados. Puedes usar fired_at como fecha y hora del evento original, y el id del mensaje como identificador único para detectar duplicados.

Eventos

Los eventos se describen en detalle en un artículo específico de nuestra Base de conocimiento.

Edición o eliminación de webhooks

Todos tus webhooks aparecerán en la lista de la página principal de Webhooks. Una vez creado, puedes editar en cualquier momento cualquier información que hayas configurado. Desplaza el ratón sobre el webhook de la lista y a continuación, pulsa el icono de puntos suspensivos de la fila del webhook. En el menú desplegable, selecciona el elemento Editar.

Se te redirigirá a la página de configuración del webhook, donde podrás editar cualquiera de los campos que hayas configurado previamente, incluidos el nombre, URL de carga útil, eventos del webhook e información de autenticación básica. Cuando hayas terminado con tus ediciones, pulsa Guardar cambios.

Para eliminar un webhook, desplaza el ratón sobre el webhook de la lista y a continuación, pulsa el icono de puntos suspensivos de su fila. En el menú desplegable, selecciona el elemento Eliminar. Confirma tu elección en el mensaje emergente marcando que deseas continuar y pulsando Confirmar.

Ten en cuenta que la eliminación de un webhook eliminará por completo la opción de usarlo de nuevo en el futuro. Si simplemente no deseas ejecutar el webhook durante un cierto periodo de tiempo, utiliza la funcionalidad de desactivación. Antes de eliminar un webhook, asegúrate de haber recibido toda la información que necesitas. 

Nota sobre la edición o eliminación de webhooks

• Cuando edites o elimines un webhook, ten en cuenta que es posible que el cambio no tenga lugar de inmediato. Los webhooks forman una cola de trabajo para Docebo, por lo que cualquier trabajo que aún esté en ejecución o en cola antes de que se realicen los cambios se enviará al extremo configurado para el webhook en el momento en que este se desencadene.
• La eliminación del webhook no eliminará ningún dato que hayas enviado anteriormente.

Activación o desactivación de webhooks

La marca de verificación de la columna Estado de un webhook en la página principal de Webhooks te permite ver y cambiar rápidamente qué webhooks están actualmente habilitados o deshabilitados. Una marca de verificación verde significa que el webhook está habilitado para ejecutarse, mientras que una gris significa que está deshabilitado y por lo tanto, no se desencadenará.

Pulsa la marca de verificación de la fila del webhook para activarlo o desactivarlo.

Notas importantes sobre la desactivación de webhooks

• Solo puedes tener habilitados hasta diez webhooks a la vez, para un máximo de 80 eventos.
• Cuando deshabilites un webhook, ten en cuenta que el cambio puede no tener lugar de inmediato. Los webhooks forman una cola de trabajo en Docebo; cualquier trabajo que aún esté en ejecución o en cola antes de que se produzcan los cambios se enviará al extremo configurado.

Webhooks y Registro de auditoría

Con la funcionalidad Registro de auditoría puedes realizar un seguimiento de las siguientes acciones relacionadas con webhooks en los informes de tus Registros:

Más detalles sobre el informe Registro de auditoría.

Orden de entrega de eventos y cardinalidad

Dependiendo de la integración que planees desarrollar utilizando webhooks de Docebo, es posible que necesites gestionar los eventos de manera ordenada. Por ejemplo, supongamos que quieres definir un webhook que envíe datos para crear, modificar y eliminar un usuario. 

Para estas operaciones, el orden en que recibas los eventos es extremadamente importante. Aunque Docebo hará todo lo posible para garantizar una entrega ordenada, el sistema de tolerancia a fallos de la implementación no permite a Docebo garantizar absolutamente que el envío de eventos tenga lugar exactamente en el orden en que ocurran. Por lo tanto, sugerimos implementar un sistema de restablecimiento de eventos antes de que tu integración los consuma realmente.

Por las mismas razones, también es necesario que puedas descartar eventos duplicados haciendo que tu extremo sea idempotente porque, bajo ciertas condiciones, la implementación del webhook podría enviar el mismo mensaje varias veces. Por ejemplo, el mismo evento podría enviarse varias veces porque la plataforma espera 5 segundos una respuesta del extremo antes de enviarlo de nuevo.

Notas sobre orden de entrega de eventos y cardinalidad

• Asegúrate de supervisar los eventos duplicados en tu plataforma.
• Aunque que el sistema de envío pone en cola los mensajes en tiempo real, es posible que la entrega de uno de ellos se posponga durante un tiempo variable debido a la cantidad de elementos en cola y al sistema de limitación vigente. 
• Aunque Docebo intenta minimizar el tiempo de espera antes del envío, la gestión correcta de los mensajes pospuestos es responsabilidad del extremo receptor. 

Limitación de mensajes

Por razones de rendimiento, Docebo ha establecido ciertos límites técnicos para garantizar que no envíe demasiados datos a un solo extremo en un período de tiempo concreto. Los mensajes se envían a un ritmo aproximado de uno por segundo.