Presentación

En Docebo puede crear webhooks para que se desencadenen cuando se produzca un evento en su plataforma y le envíen información sobre dicho evento a una URL de carga útil específica. Esto le permite recopilar datos de su plataforma de aprendizaje para crear informes, integraciones o paneles de control, entre otras cosas. También puede, por ejemplo, conectarse a su sistema de gestión de recursos humanos, 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 su contenido.

Cuando haya activado la aplicación Webhooks en su plataforma, puede crear una entrada de un evento inicial, Docebo colocará los datos relacionados con ese evento en un mensaje JSON y lo enviará mediante una llamada HTTP, HTTPS POST, EventBridge o SQS (no por correo electrónico o notificaciones) a una URL determinada que haya configurado para el webhook emparejado con ese evento.

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

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

Consejo: Esta aplicación solo puede ser gestionada por Superadministradores. Los Usuarios avanzados no tienen permisos para ver o gestionar webhooks.

Activar la aplicación Webhooks

Active la aplicación Webhooks como se describe en el artículo Gestión de aplicaciones y características de la Base de conocimientos. La aplicación aparece listada en la pestaña Características adicionales de Docebo.

Crear y editar webhooks

Una vez activada la aplicación, puede gestionarla accediendo al Menú de administrador y pulsando el elemento Gestionar de la sección Webhooks. En la página principal Webhooks puede añadir y gestionar todos sus webhooks, activarlos o desactivarlos, editarlos o eliminarlos y comprobar los errores de sistema externos, si los hay.

Para añadir un webhook, pulse el botón más de la esquina superior derecha de la página.

Dependiendo del tipo de webhook que desee crear, el proceso en el siguiente panel será diferente de la siguiente manera:

Webhooks HTTP y HTTPS

En el panel que se abrirá, póngale un nombre significativo a su webhook, seleccione HTTP como tipo de webhook y, en el campo URL de carga útil, introduzca la URL del webhook. También puede elegir si desea que su plataforma agrupe eventos. Para más información sobre la agrupación de eventos, vea el capítulo Colección de carga útil de este artículo. A continuación, pulse Siguiente para continuar.

A tener en cuenta: El tipo de webhook no se puede cambiar una vez que se haya realizado la selección y guardado el webhook. Si elige el tipo incorrecto aquí, tendrá que volver a crear el webhook de nuevo.

Webhooks de SQS

Consejo: La disponibilidad de este tipo de webhook depende de su plan de precios.

En el panel que se abrirá, póngale un nombre significativo a su webhook, seleccione SQS como tipo de webhook y, en el campo ARN, introduzca la dirección ARN del webhook. Recuerde que no puede cambiar el parámetro de la región. A continuación, pulse el icono Copiar en la sección Autenticación para copiar el ID de la cuenta en su portapapeles. Deberá conceder a este ID permiso para impulsar eventos en su sistema. También puede elegir si desea que su plataforma agrupe eventos. Para más información sobre la agrupación de eventos, vea el capítulo Colección de carga útil de este artículo. A continuación, pulse Siguiente para continuar.

A tener en cuenta: El tipo de webhook no se puede cambiar una vez que se haya realizado la selección y guardado el webhook. Si elige el tipo incorrecto aquí, tendrá que volver a crear el webhook de nuevo.

Webhooks de EventBridge

Consejo: La disponibilidad de este tipo de webhook depende de su plan de precios.

En el panel que se abrirá, póngale un nombre significativo a su webhook, seleccione EventBridge como tipo de webhook y, en el campo ARN, introduzca el ARN del webhook. Recuerde que no puede cambiar el parámetro de la región. A continuación, pulse el icono Copiar en la sección Autenticación para copiar el ID de la cuenta en su portapapeles. Deberá conceder a este ID permiso para impulsar eventos en su sistema. También puede elegir si desea que su plataforma agrupe eventos. Para más información sobre la agrupación de eventos, vea el capítulo Colección de carga útil de este artículo. A continuación, pulse Siguiente para continuar.

A tener en cuenta: El tipo de webhook no se puede cambiar una vez que se haya realizado la selección y guardado el webhook. Si elige el tipo incorrecto aquí, tendrá que volver a crear el webhook de nuevo.

A continuación, en el panel, puede seleccionar hasta ocho eventos para incluirlos en el webhook. Después, pulse Crear.

El nuevo webhook se mostrará en la lista de la página principal Webhooks y estará desactivado de forma predeterminada. A continuación, pulse el menú de puntos suspensivos al final de la fila de su webhook recién creado. En el menú desplegable que se abrirá, pulse Editar.

En la siguiente ventana podrá editar todos los aspectos del webhook, excepto el tipo de webhook. Si necesita modificar o añadir eventos al webhook, puede pulsar el botón X de cada evento para eliminar el evento seleccionado; de forma alternativa, puede pulsar el botón más al final de la lista Eventos para añadir eventos del mismo modo que cuando creó el webhook por primera vez. Encontrará más detalles sobre cada webhook y las cargas útiles con formato JSON correspondientes para estos en el artículo Eventos de webhooks.

Si desea modificar la URL de destino o necesita habilitar la autenticación básica para su webhook en el caso de los webhooks HTTP/S, vaya a la pestaña Información del extremo. Aquí, en la pantalla resultante, puede editar el campo URL de carga útil o introducir el nombre de usuario y la contraseña necesarios para la autenticación básica marcando la casilla de verificación Habilitar autenticación básica.

Práctica recomendada: Docebo recomienda encarecidamente usar HTTPS y habilitar la autenticación básica al usar webhooks HTTP, pues añade seguridad a la información que la plataforma envía a su extremo.

Cuando haya terminado de realizar sus cambios, presione el botón Guardar cambios.

A continuación, una vez completados todos los pasos de la configuración, puede habilitar el webhook pulsando el menú de puntos suspensivos al final de la fila del webhook correspondiente y seleccionando Activar en el menú desplegable que se abrirá.

Observará que el estado del webhook en sus listas de webhooks ha cambiado a Activo.

A tener en cuenta:

• El campo URL de carga útil debe ser una URL HTTP, una URL HTTPS, una dirección SQS o una dirección EventBridge con el formato correcto. Puede insertar una URL de carga útil por webhook y puede agregar hasta ocho eventos por webhook, de modo que pueda enviar información para más de un evento a esta URL de carga útil única receptora.
• Si bien no hay límite en la cantidad de webhooks que puede crear o configurar, por razones de rendimiento, puede tener un máximo de diez webhooks habilitados en su plataforma en un momento dado. Tenga esto en cuenta al crear y habilitar sus webhooks.
• Cuando se trate de rotación de autenticación básica y contraseña, asegúrese de permitir que la contraseña antigua siga siendo válida durante un tiempo, dependiendo de su tráfico. Los mensajes antiguos se autenticarán usando las contraseñas antiguas; si ya no las acepta, esos mensajes resultarán fallidos.
• Realice siempre un seguimiento de los correos electrónicos de notificación para detectar 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.
• Separe sus webhooks en diferentes dominios (domain1.webhook.com, domain2.webhook.com, etc.) para garantizar que los webhooks para su plataforma se gestionen mediante colas paralelas si espera una alta tasa de mensajes. Esto no es necesario para un tráfico bajo, pero agruparlos en distintas colas puede optimizar los tiempos de entrega.
• Tenga en cuenta que Docebo no admite colas FIFO y no acepta direcciones .fifo en el campo ARN al crear un webhook.

Desactivar webhooks

Si necesita desactivar el webhook, solo tiene que pulsar el menú de puntos suspensivos al final de la fila del webhook y, en el menú desplegable que se abrirá, seleccione Desactivar.

A tener en cuenta:

• Solo puede tener un máximo de diez webhooks activados a la vez, para un máximo de 80 eventos.
• Cuando desactive un webhook, recuerde que el cambio podría no producirse de inmediato. Los webhooks forman una cola de trabajo en Docebo; cualquier trabajo que siga en ejecución o en la cola de trabajo antes de que tengan lugar los cambios se seguirá enviando al extremo configurado.

Eliminar webhooks

Si desea eliminar su webhook, solo tiene que pulsar el menú de puntos suspensivos al final de la fila del webhook que desee eliminar y, en el menú desplegable que se abrirá, pulsar Eliminar.

Aparecerá un mensaje de confirmación. Para confirmar la eliminación, pulse la tecla Eliminar.

A tener en cuenta:

• Recuerde que al eliminar un webhook se eliminará por completo la opción de volver a utilizarlo en el futuro. Si simplemente no desea ejecutar el webhook durante un tiempo, utilice en su lugar la funcionalidad de desactivar. Antes de eliminar un webhook, asegúrese de haber recibido toda la información que necesite antes de confirmar la eliminación.
• Al eliminar el webhook no se eliminará ningún dato que enviara previamente.
• Cuando elimine un webhook, recuerde que el cambio podría no producirse de inmediato. Los webhooks forman una cola de trabajo en Docebo; cualquier trabajo que siga en ejecución o en la cola de trabajo antes de que tengan lugar los cambios se seguirá enviando al extremo configurado.

Cargas útiles de webhooks

Colección de carga útil

Cuando esté configurando o editando su webhook, en la sección Colección de carga útil podrá definir si agrupar las cargas útiles relacionadas con los eventos del mismo tipo y generadas por el mismo proceso en una sola entrega de mensajes. Por ejemplo, cuando esta opción esté activada, 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 con diez eventos de cursos creados en lugar de diez mensajes de webhooks por separado, uno para cada curso.

A tener en cuenta: Activar esta opción no garantiza que el número de eventos incluidos en una colección de carga útil equivalga al número de eventos generados por el proceso desencadenante (en nuestro ejemplo, la llamada API). El número de eventos recopilados en los webhooks cambia en función de la lógica de optimización del búfer de la infraestructura de la plataforma. Volviendo a nuestro ejemplo, cuando la llamada API desencadene la creación de diez cursos, en función de la lógica de optimización del búfer puede que reciba un webhook con una colección de diez eventos, dos webhooks con ocho eventos cada uno o un webhook que recopile nueve eventos más un webhook de evento único.

Cuando los webhooks incluyen más de un evento, la propiedad común del webhook carga útil se convierte en cargas útiles, indicando que el mensaje incluye varios eventos.

Práctica recomendada: Si ha habilitado la función de colección de carga útil, asegúrese de que su sistema de extremos esté preparado para recibir webhooks con dos estructuras diferentes.

Cuando haya terminado de configurar su webhook, presione el botón Guardar cambios.

Habilitar datos adicionales para la carga útil

Dependiendo de sus necesidades, puede que desee activar datos adicionales para la carga útil, de modo que la información que se transmita a sistemas externos sea más detallada. Hay disponibles datos adicionales para cursos, seminarios web, inscripciones y planes de aprendizaje. Si le interesa activar datos adicionales, póngase en contacto con la asistencia a través del Centro de ayuda.

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

A tener en cuenta:

• Tenga 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 su URL de carga útil. Si desea más información, debe consultar directamente la carga útil. Puede identificar el ID de los recursos actualizados a través del webhook y, a continuación, volver a efectuar la llamada API adecuada para las actualizaciones.
• Las cargas útiles de webhooks siempre incluyen un parámetro id que tiene 56 caracteres de longitud.
• Identifique qué eventos de webhooks pueden ocurrir después de acciones masivas y habilite cargas útiles agrupadas en ellos. Cuando Docebo Learn realiza una acción intensiva que desencadena varios eventos del mismo tipo en un periodo de tiempo muy corto, el webhook enviado puede contener varias cargas útiles del mismo tipo de evento en un mensaje. Esto garantiza un menor número de mensajes para entregar, lo que le 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. Tenga en cuenta también que, si Docebo no recibe una respuesta en un plazo de 5 segundos a partir del envío de la solicitud, esta se considera un error y se registra como tal, incluso si el servidor remoto puede estar procesando la solicitud pero simplemente no ha respondido a tiempo. Consulte el artículo sobre la gestión de errores para obtener más información.

Eventos de webhooks

Encontrará todos los detalles sobre los eventos en el artículo específico de nuestra Base de conocimientos.

Webhooks y el registro de auditoría

Con la funcionalidad Registro de auditoría puede realizar un seguimiento de las siguientes acciones relacionadas con webhooks en los informes de su registro de auditoría:

Evento del registro de auditoría	Descripción del evento
Webhook creado	Acción registrada cuando se crea un webhook
Webhook actualizado	Acción registrada cuando se actualiza un webhook
Webhook eliminado	Acción registrada cuando se elimina un webhook
Webhook activado	Acción registrada cuando se activa un webhook
Webhook desactivado	Acción registrada cuando se desactiva manualmente un webhook
Webhook desactivado por el sistema	Acción registrada cuando el sistema desactiva automáticamente un webhook de acuerdo con la Política de reintentos definida aquí

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

Orden de entrega de eventos y cardinalidad

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

Para estas operaciones, el orden en que reciba 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 de forma absoluta 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 su integración los consuma realmente.

Por las mismas razones, también es necesario que pueda descartar eventos duplicados haciendo que su extremo sea idempotente porque, en determinadas 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.

A tener en cuenta:

• Asegúrese de supervisar los eventos duplicados en su 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 sea pospuesta por 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 periodo de tiempo concreto. Los mensajes se envían a un ritmo aproximado de uno por segundo.

Notas importantes sobre los webhooks de SQS y Eventbridge

Registros de webhooks

Si el integrador no responde (o el destino del ARN no se ha establecido correctamente), se realizará un seguimiento de los errores en nuestro registro de errores actual. Solo los errores disponibles a través de la interfaz de usuario se rastrearán en el registro o se enviarán a través de notificaciones por correo electrónico.

Política de reintentos

Si, por algún motivo, el webhook no puede recibir el mensaje (por ejemplo, debido a que la dirección de la cola o las credenciales sean incorrectas), después del primer intento Docebo volverá a intentar enviar el evento otras 5 veces sin retraso alguno entre un intento y otro. AWS, por su parte, tomará cada uno de dichos reintentos y lo probará tres veces, dando lugar a un total de 15 reintentos. Para más información, consulte el Comportamiento de reintentos de AWS (se abre en una nueva pestaña). Si todos los reintentos fallan, el webhook se desactivará automáticamente.

Cola de mensajes fallidos

Si la política de reintentos alcanza el número máximo de intentos de envío, el webhook se almacenará en un repositorio temporal de Docebo. El repositorio está encriptado y el acceso a los registros se puede obtener mediante la API dedicada. Para obtener más información, consulte Webhooks: Gestión de errores.

Política de conservación

El mensaje se guardará durante 60 días. Pasado este tiempo, el mensaje se eliminará de forma permanente.