Saltearse al contenido

AcademIA Webhook

AcademIA Webhook es un componente de inicio: pone en marcha el flujo cada vez que AcademIA comunica un evento de aprendizaje, por ejemplo que alguien termina una lección, aprueba o suspende un cuestionario, completa un curso o consigue un certificado. Cada evento es una ejecución del flujo.

AcademIA envía su actividad en el formato estándar de la formación en línea, xAPI, a lo que llama un LRS (Learning Record Store, el registro donde se guarda la actividad formativa). Este componente hace de LRS para tu flujo: recibe cada evento y lo convierte en datos sencillos, como quién ha sido, qué curso o lección, la nota y la fecha.

Cuándo usarlo

  • Felicitar por correo a cada alumno que completa un curso.
  • Avisar a su responsable cuando alguien suspende un cuestionario.
  • Registrar en tu CRM o en el sistema de Recursos Humanos los certificados que se emiten.
  • Llevar a una hoja de cálculo el progreso de la formación de tu equipo.

Configuración

Es AcademIA quien llama al flujo. Para que el componente compruebe que las llamadas vienen de AcademIA, crea una credencial AcademIA xAPI con un Shared secret: un valor largo y aleatorio que eliges tú y que solo conocerán el flujo y AcademIA. Consulta Credenciales.

CampoQué hace
EventsLos eventos que ponen en marcha el flujo. Los demás se ignoran. Por defecto están todos marcados.
CredentialOpcional, pero recomendada. La credencial AcademIA xAPI con el secreto compartido (Shared secret). Con ella, se rechaza cualquier llamada que no traiga ese secreto. Sin credencial, no se comprueba.
Skip repeated deliveries (avanzado)Activado por defecto. AcademIA vuelve a enviar un evento cuando la respuesta tarda; así el mismo hecho solo ejecuta el flujo una vez.
Run on test statements (avanzado)Desactivado por defecto. El botón Probar conexión de AcademIA envía una matrícula de prueba: se acepta, pero no ejecuta el flujo salvo que actives esta opción.
DataSirve para probar el componente en el editor: pega aquí un evento de ejemplo y ejecuta el flujo. Cuando el flujo se ejecuta por su webhook, se rellena con lo recibido. Déjalo vacío.

Estos son los eventos y cómo se llaman en AcademIA:

Evento en EventsQué ha pasadoEn AcademIA, en Eventos que se envían
EnrollmentAlguien se ha matriculado en un curso.Matriculación en un curso
Lesson CompletedAlguien ha terminado una lección.Lección completada
Quiz PassedAlguien ha aprobado un cuestionario.Cuestionario evaluado
Quiz FailedAlguien ha suspendido un cuestionario.Cuestionario evaluado
Game CompletedAlguien ha completado una actividad de juego.Actividad de juego completada
Path CompletedAlguien ha completado un curso (una ruta de aprendizaje).Curso completado
Certificate IssuedAcademIA ha emitido un certificado.Certificado emitido

Configurarlo en AcademIA

  1. Crea la credencial AcademIA xAPI con un valor largo y aleatorio en Shared secret y elígela en el campo Credential del componente.
  2. Despliega una versión del flujo: las llamadas al webhook ejecutan la versión desplegada. Ver Versiones y publicación.
  3. Abre la ventana Acceso a API, ve a la pestaña Webhook, elige la Clave API y copia la dirección. Tiene esta forma: <dirección de la API de NappAI>/api/v1/webhook/<id del flujo>?x-api-key=<clave API>. La clave va dentro de la dirección porque AcademIA no puede añadir cabeceras a sus envíos. Ver Claves API.
  4. Entra en AcademIA con un usuario Admin corporativo (CORPORATE_ADMIN) de tu organización. En el menú, en la sección Avanzado, abre LRS (xAPI). Esta integración necesita el plan ENTERPRISE de AcademIA.
  5. En Endpoint xAPI pega la dirección del flujo.
  6. Deja vacío Usuario (Basic Auth) y escribe en Credencial la palabra Bearer, un espacio y el mismo valor que guardaste en el Shared secret de la credencial AcademIA xAPI. Por ejemplo, si el secreto es k8Qz…, escribe Bearer k8Qz….
  7. En Eventos que se envían, marca los mismos eventos que en Events. Si quieres recibir el nombre y el correo de cada persona, activa Incluir nombre y correo reales del alumno.
  8. Pulsa Guardar y después Probar conexión. AcademIA envía una matrícula de prueba y te dice si la ha aceptado.

Un Super admin de AcademIA puede hacer lo mismo en el LRS de la plataforma, que recoge la actividad de los usuarios que no pertenecen a ninguna organización.

Resultado

La salida Data entrega el evento con estos datos:

  • event: el evento, por ejemplo Quiz Failed.
  • user_id: el identificador de la persona en AcademIA.
  • email y name: el correo y el nombre de la persona. Solo llegan si en AcademIA está activado Incluir nombre y correo reales del alumno.
  • activity_type (course, lesson, assessment o interaction), activity_id y activity_name: el curso, la lección, el cuestionario o el juego.
  • score (de 0 a 100), success (si ha aprobado) y completion (si lo ha terminado).
  • game_type y xp_earned en los juegos.
  • certificate_url y certificate_hash en los certificados emitidos.
  • timestamp: cuándo ocurrió.
  • statement: el evento completo, tal como lo envió AcademIA.

Si llega un evento que no está marcado en Events, un evento de prueba o una entrega repetida, el flujo se detiene en este componente sin dar error.

Ejemplo

Una empresa quiere enviar el diploma a cada empleado que termina un curso.

  1. Añade AcademIA Webhook, elige su credencial AcademIA xAPI y deja marcado solo Certificate Issued en Events.
  2. Conecta Data a AcademIA Certificates con la operación Verify Certificate y, en Certificate, el dato certificate_hash del evento. Para comprobar un certificado por su código, la clave de la credencial AcademIA tiene que actuar como Admin de contenido o Super admin.
  3. Conecta el resultado a un agente que redacte la felicitación y a Gmail Message para enviarla al correo de la persona con el enlace certificate_url.
  4. Despliega el flujo y configúralo en AcademIA como LRS de la organización, con el evento Certificado emitido y Incluir nombre y correo reales del alumno activado.

Buenas prácticas

  • Usa siempre una credencial AcademIA xAPI. Sin ella, cualquiera que tenga la dirección del flujo puede ponerlo en marcha.
  • Marca los mismos eventos en AcademIA y en Events: lo que AcademIA no envía no llega nunca, y lo que envía de más solo ocupa ejecuciones que se descartan.
  • Si no activas el correo en AcademIA, identifica a la persona por user_id y consulta sus datos con AcademIA Organization, operación Get Member.
  • Un flujo solo puede tener un componente de webhook.

Seguridad y limitaciones

  • AcademIA no firma sus envíos: la protección es el secreto de la credencial AcademIA xAPI y la clave API de la dirección. Si cambias el secreto, cámbialo a la vez en la credencial y en AcademIA. No compartas la dirección del flujo.
  • AcademIA solo envía el evento Enrollment cuando la persona se matricula por su cuenta. Las matrículas que hace una empresa al asignar un curso, o las que vienen de una invitación, no lo generan.
  • El nombre y el correo son datos personales que AcademIA cede al flujo. Actívalos solo si tu contrato y tu información de privacidad lo cubren.
  • Al probar pegando un evento en Data no se comprueba el secreto: solo se comprueba en las llamadas reales.

Componentes relacionados