Presentación

En Docebo, puede crear webhooks para que se desencadenen una vez que tenga lugar un evento en su plataforma, enviándole información sobre ese evento a una URL de carga útil específica. Esto le permite recopilar datos de su plataforma de aprendizaje para crear informes, integraciones y paneles de control, entre otras cosas. También puede conectarse a su sistema de gestión de recursos humanos (HCM), enviar correos electrónicos a usuarios externos al LMS sobre acciones en la plataforma o actualizar su CSM. Más información sobre los webhooks.

Para reconocer la recepción de un webhook, Docebo espera un código de estado HTTP 2xx en la respuesta o un código de estado HTTP 3xx. En cualquier otro caso, Docebo marcará el envío como fallido. Los fallos se registran como errores en el registro de la plataforma para que pueda revisarlos y tomar medidas.

Revisión de errores

Para examinar cualquier error de un webhook registrado en su plataforma, acceda al Menú de administrador y, a continuación, seleccione el elemento Gestionar en la sección Webhooks. En la página principal Webhooks, consulte la columna Último error de sistema externo para la fila de cada webhook.

Esta columna muestra el último mensaje de error recibido desde el sistema externo. Aunque la plataforma haya recibido múltiples mensajes de error, únicamente mostrará el último error recibido del webhook, por lo que es responsabilidad suya determinar si el error mostrado es el único recibido o el último de varios errores del webhook.

Asimismo, esta columna no siempre refleja el error de la última llamada. Esto implica que se mostrará el último error registrado, incluso si las llamadas posteriores al error fueron exitosas. Docebo proporciona esta información debido a que aplica una política de retroceso exponencial, la cual establece una política de reintentos en caso de fallo en la llamada, si bien con un límite definido.

Pase el cursor sobre el código del error para ver la marca temporal del último error registrado; esta información le proporcionará detalles adicionales para facilitarle la comprensión de la situación.

Haga clic en el menú de puntos suspensivos al final de la fila del webhook y seleccione Restablecer error del sistema en el menú desplegable para restablecer el valor de la columna a su estado predeterminado (sin errores), con el fin de realizar pruebas. Tenga en cuenta que, al seleccionar esta opción, solo se actualiza el valor de la columna; no se elimina el error.

Haga clic en el nombre del webhook y vaya a la pestaña Registro de errores para obtener una vista más detallada de los errores registrados. Esta pestaña enumera todos los errores registrados para el webhook seleccionado; tenga en cuenta que cargar la totalidad de los errores disponibles puede llevar unos minutos. Utilice la función de búsqueda para localizar un texto en cualquiera de las columnas disponibles.

Haga clic en el icono de filtros en la esquina superior izquierda de la tabla para filtrar los errores mostrados por periodo de tiempo, nombre del evento o tipo de error. Tenga en cuenta que el filtro Tipo de error solo incluye los códigos de errores efectivamente registrados; si un código de error no ha sido registrado para la carga útil seleccionada, no aparecerá en el área Filtros.

Para visualizar la carga útil que generó el error, haga clic en el menú de puntos suspensivos al final de la fila de la URL de carga útil y seleccione la opción Ver carga útil.

Política de reintentos

Tras enviar un webhook, Docebo espera durante cinco segundos una respuesta del extremo para confirmar su recepción.

En caso de errores o ausencia de respuesta del sistema externo, Docebo añadirá los siguientes mensajes al registro de errores, según corresponda:

Docebo intentará reenviar el webhook con la misma carga útil hasta diez veces (después de la primera llamada) y desactivará automáticamente el webhook tras registrar el décimo error, para que pueda corregir el problema con la llamada y reconfigurar el webhook en caso necesario.

Consejo: Recuerde que debe reactivar manualmente el webhook después de que haya sido desactivado; no se reactivará automáticamente

Dado que la entrega de un mensaje de un webhook puede fallar por diversas razones (tiempos de espera, errores HTTP, host inalcanzable, etc.), un mensaje no entregado será reprogramado y reenviado.

Los webhooks se reenvían conforme al siguiente cronograma de tiempos:

Cada mensaje se entrega como máximo diez veces, teniendo lugar el último reintento poco más de 61 horas después del primer intento antes de ser descartado. Cuando un mensaje es descartado, se coloca en una Cola de mensajes no entregados (DLQ).

Consejo: El contador de errores del webhook se basa en cada carga útil que compone el webhook. Esto significa que, si una sola carga útil genera diez errores, todo el webhook será deshabilitado. Tenga presente que los errores de las cargas útiles no se combinan. Por ejemplo, si el Webhook 1 es desencadenado por dos eventos diferentes con Carga útil A y Carga útil B, cuando Carga útil A genera ocho errores y Carga útil B dos, el webhook no se deshabilita. Solo se deshabilitará cuando bien Carga útil A o bien Carga útil B alcance el décimo error.

La desactivación automática del webhook puede ser rastreada mediante la función del Registro de auditoría.

A tener en cuenta: En caso de que su extremo no pueda manejar la cantidad de datos enviados por Docebo en un tiempo determinado, recibirá un código de respuesta 426 u otros códigos similares. Estos códigos generalmente indican que todo está dentro de los parámetros de Docebo, pero su extremo no es capaz de recibir la cantidad de datos enviados. Cuando esto ocurre, Docebo continúa con los reintentos conforme a la política de retroceso exponencial habitual, pero los reintentos finalizarán después del ciclo normal si no se reciben respuestas.

Política de retención de webhooks - Cola de mensajes no entregados

Los mensajes de webhooks que hayan fallado tras diez reintentos se añaden a la Cola de mensajes no entregados y pueden recuperarse, mediante su ID, a través de la siguiente llamada API GET:

/notifications/v1/webhooks/{webhook_id}/dlq

Esta lista puede eliminarse mediante la siguiente llamada API DELETE:

/notifications/v1/webhooks/{payload_ids}/dlq/batch

Consulte la documentación en su Navegador de API para obtener más información sobre el funcionamiento de estos extremos y cómo llamarlos.

A tener en cuenta: Cuando un mensaje se almacena en la Cola de mensajes no entregados y alcanza los 60 días de antigüedad, el mensaje del webhook se elimina automáticamente del sistema.

Códigos de errores

Este capítulo enumera los posibles códigos de errores que pueden ser registrados por el sistema:

A tener en cuenta: Docebo no proporciona soporte para los errores externos, dado que estos no provienen de Docebo, ni para los webhooks mal configurados. Docebo únicamente puede confirmar si una llamada HTTP fue enviada desde su sistema.

Activación de notificaciones para errores de webhooks

Los webhooks se utilizan en procesos diarios, y activar notificaciones en caso de errores facilita su debida gestión. Para gestionar las notificaciones, acceda a la página Webhooks y vaya a la pestaña Notificaciones. Habilite las notificaciones marcando la opción correspondiente y configure la lista de destinatarios. La lista de destinatarios acepta únicamente direcciones de correo electrónico verificadas asociadas a usuarios de la plataforma. No se permiten direcciones de correo electrónico no vinculadas a un usuario de la plataforma.

Puede añadir hasta cinco destinatarios. Si necesita notificar a más personas, se recomienda utilizar una lista de distribución mediante la creación de un usuario en la plataforma para este fin, utilizando la dirección de correo electrónico asociada para la lista de distribución. Dado que este usuario no accederá a cursos ni activos, no será considerado un usuario activo y no afectará al periodo de facturación.

A tener en cuenta: Las notificaciones de webhooks están integradas en la funcionalidad de los webhooks y no son gestionadas por la aplicación Notificaciones de Docebo, ya que son mensajes del sistema con un propósito técnico y su contenido no requiere gestión adicional.

La funcionalidad de los webhooks gestiona dos tipos de notificaciones:

• Error único
  El destinatario será notificado acerca del código de error, la descripción, el webhook que generó el error, el nombre de la plataforma y el dominio donde se produjo. La notificación se estructura de la siguiente manera:

  Asunto: ¡ATENCIÓN! ¡Error en el extremo del webhook!
  
  Hola,
  
  Queremos informarle de que el extremo configurado para el webhook "[webhook_name]" 
  de la plataforma "[domain]" ha generado el siguiente error: 
  "[error_code][error_description]".
  
  ¡Por favor, revíselo!

• Error repetido y desactivación del webhook
  El destinatario será notificado de que un webhook ha generado errores repetidos y, por ende, será desactivado conforme a la Política de reintentos descrita en este documento. La notificación incluye el código de error, la descripción, el webhook que generó el error, el nombre de la plataforma y el dominio donde se produjo, además de un mensaje instando a reactivar manualmente el webhook una vez resuelto el problema. La notificación se presenta de la siguiente manera:

  Asunto: ¡ATENCIÓN! ¡Webhook desactivado en su plataforma <platform_name>! 
  
  Hola, queremos informarle de que el extremo configurado para el webhook "[webhook_name]" 
  de la plataforma "[domain]" ha generado repetidamente el siguiente 
  error: "[error_code][error_description]", y Docebo lo ha desactivado.  
  
  Por favor, revíselo y reactive el webhook cuando el problema haya sido solucionado.