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.
| Campo | Qué hace |
|---|---|
| Events | Los eventos que ponen en marcha el flujo. Los demás se ignoran. Por defecto están todos marcados. |
| Credential | Opcional, 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. |
| Data | Sirve 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 Events | Qué ha pasado | En AcademIA, en Eventos que se envían |
|---|---|---|
Enrollment | Alguien se ha matriculado en un curso. | Matriculación en un curso |
Lesson Completed | Alguien ha terminado una lección. | Lección completada |
Quiz Passed | Alguien ha aprobado un cuestionario. | Cuestionario evaluado |
Quiz Failed | Alguien ha suspendido un cuestionario. | Cuestionario evaluado |
Game Completed | Alguien ha completado una actividad de juego. | Actividad de juego completada |
Path Completed | Alguien ha completado un curso (una ruta de aprendizaje). | Curso completado |
Certificate Issued | AcademIA ha emitido un certificado. | Certificado emitido |
Configurarlo en AcademIA
- Crea la credencial AcademIA xAPI con un valor largo y aleatorio en Shared secret y elígela en el campo Credential del componente.
- Despliega una versión del flujo: las llamadas al webhook ejecutan la versión desplegada. Ver Versiones y publicación.
- 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. - 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. - En Endpoint xAPI pega la dirección del flujo.
- 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 esk8Qz…, escribeBearer k8Qz…. - 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.
- 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 ejemploQuiz Failed.user_id: el identificador de la persona en AcademIA.emailyname: 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,assessmentointeraction),activity_idyactivity_name: el curso, la lección, el cuestionario o el juego.score(de 0 a 100),success(si ha aprobado) ycompletion(si lo ha terminado).game_typeyxp_earneden los juegos.certificate_urlycertificate_hashen 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.
- Añade AcademIA Webhook, elige su credencial AcademIA xAPI y deja marcado solo
Certificate Issueden Events. - Conecta Data a AcademIA Certificates con la operación
Verify Certificatey, en Certificate, el datocertificate_hashdel 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. - 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. - 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_idy consulta sus datos con AcademIA Organization, operaciónGet 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
Enrollmentcuando 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
- AcademIA Organization: miembros, rutas y analíticas de una empresa.
- AcademIA Enrollment: invitaciones a rutas y matrículas en programas.
- AcademIA Certificates: verificar y listar certificados.
- Webhook Input: el webhook genérico, para cualquier otra aplicación.