Webhooks de la API de integración
Un webhook es un aviso automático que Eduvem envía a otro sistema en el momento en que algo sucede - sin que ese sistema tenga que estar preguntando “¿y ahora, cambió algo?”. Con webhooks, cuando la matrícula de un Participante cambia de estado, recibe un certificado o completa una ruta, Eduvem “empuja” esa información al instante hacia la dirección que su equipo de integración indique (el RH, un BI, un sistema interno).
Es la alternativa “en tiempo real” a la consulta periódica: en vez de que su sistema pregunte cada tanto qué cambió, Eduvem avisa por sí sola en el momento en que cambia.
Para quién es este recurso
Sección titulada «Para quién es este recurso»Configurar webhooks involucra a dos personas con roles diferentes:
- El administrador de la institución (usted) otorga el permiso en un token de la API. Es lo que cubre este artículo.
- Su equipo de integración (quien programa) usa ese token para registrar las direcciones que recibirán los avisos y para procesar cada aviso recibido. Esa parte técnica está en la documentación de la API.
Habilitando el permiso de webhooks en un token
Sección titulada «Habilitando el permiso de webhooks en un token»Los webhooks se gestionan con los mismos tokens de API usados por el resto de la integración - no hay una credencial separada. La capacidad de gestionar webhooks está detrás de un permiso específico, que viene desactivado de forma predeterminada: webhooks:manage.
- En el panel administrativo, abra la pestaña Integraciones de la institución.
- Cree un nuevo token de API (consulte Tokens de la API de integración). Si la integración ya tiene un token, también puede activar el permiso en él con el botón Editar permisos de la lista de tokens, sin generar un token nuevo.
- En la lista de permisos (alcances) del token, marque Webhooks (gestionar) y Informes (lectura) - inscribirse a cualquier evento exige ambos permisos juntos.
- Confirme con OK y copie el valor del token que se muestra - no volverá a mostrarse.
Un token sin el permiso Webhooks que intente gestionar webhooks recibe un rechazo de acceso. Crear o actualizar una suscripción también exige el permiso Informes (lectura) junto con Webhooks - sin él, la llamada se rechaza aunque Webhooks esté marcado; listar, probar y eliminar suscripciones no exigen Informes. Otorgar a un token permiso para leer participantes y matrículas no otorga, por sí solo, el permiso de webhooks - debe marcarse explícitamente. Como siempre, otorgue a un token solo lo que la integración realmente usa.
Los avisos quedan vinculados al token que creó o actualizó por última vez el registro del webhook. Si quita el permiso Informes (lectura) de ese token, o lo elimina, sus webhooks dejan de enviar avisos y pasan a mostrarse como tokenRevoked; los eventos de ese período no se reenvían después. Para retomar, el equipo de integración debe reactivar el webhook con un token que tenga ambos permisos. Al cambiar un token por otro, cree el nuevo, reactive cada webhook con él y solo entonces elimine el anterior.
Qué llevan los avisos (visión general)
Sección titulada «Qué llevan los avisos (visión general)»Cada aviso es una notificación firmada, enviada a la dirección que su equipo registre, informando el evento (por ejemplo, “cambio de estado de la matrícula”, “certificado emitido” o “ruta completada”) y los datos relacionados: la matrícula, la sala, el contenido y el participante. Un aviso de ruta completada es diferente: lleva al participante y la ruta (identificador y nombre), sin matrícula, sala ni contenido - una ruta reúne varias salas, así que el aviso no está ligado a una sola de ellas. Todo está aislado por institución - un aviso solo lleva datos de la institución dueña del token.
El envío del CPF dentro del aviso sigue la configuración de perfil de su institución: si el campo CPF no está habilitado en el perfil, no se envía.
Cuando la persona tiene un externalId (el código del sistema de RR. HH. cargado por la sincronización de personas), el bloque de la persona del aviso trae también person.externalId; sin él, la clave no aparece y el aviso queda como antes. Vea Documentación de la API.
Los detalles técnicos están en la documentación de la API
Sección titulada «Los detalles técnicos están en la documentación de la API»El registro de las direcciones que reciben los avisos, el catálogo completo de eventos, la verificación de la firma de seguridad, la política de reintentos y el monitoreo de las entregas los realiza el equipo de integración y están descritos en la documentación de la API. Reenvíe ese material a quien vaya a programar la integración.