Webhooks educativos: eventos duplicados y fuera de orden

La gestión académica comunica un alta y, después, una baja de matrícula. La baja llega primero al receptor. Más tarde aparece el alta antigua y, a continuación, una segunda entrega de la baja. Un programa que aplica cada mensaje según llega puede dejar al estudiante en un estado que ya no corresponde.

Un webhook es una petición que un sistema envía a otro para avisarle de un evento. La entrega puede repetirse o no conservar el orden esperado, según el contrato del emisor. El receptor tiene que distinguir el mensaje recibido, la decisión de procesarlo y el estado que finalmente conserva.

El caso es hipotético. La solución que se describe sirve para razonar sobre un receptor; no presupone que Moodle emita estos mensajes de forma nativa ni que todas las plataformas garanticen las mismas condiciones de entrega.

Confirmar recepción no significa completar la matrícula

Antes de aceptar un mensaje, el receptor comprueba su procedencia, integridad, formato y destino. La verificación de firma, si el proveedor la utiliza, debe seguir su contrato y trabajar con el contenido que ese mecanismo exige. Un campo del JSON que diga quién envía no acredita por sí solo esa identidad.

Después se decide qué significa la respuesta de recepción. Si el trabajo continúa en segundo plano, una respuesta de aceptación debe corresponder a un mensaje guardado de forma duradera o a una entrega confirmada a la cola responsable. Confirmar primero y perder el mensaje al reiniciar deja al emisor sin una razón para repetirlo.

El seguimiento del proceso necesita conservar esa diferencia: recibido, pendiente, rechazado y aplicado no son el mismo estado. El registro debe permitir localizar un mensaje aceptado que todavía no ha producido el resultado previsto.

Un identificador repetido también puede esconder una contradicción

Una clave formada por el origen verificado y el identificador del evento permite reconocer una entrega repetida. Esa clave necesita una restricción de unicidad efectiva en el registro persistente. Consultar primero si el evento existe y escribirlo después, sin protección frente a concurrencia, permite que dos trabajadores acepten el mismo a la vez.

Además guardaría una huella del contenido. Recibir la misma clave con un contenido distinto merece una revisión: no debería convertirse silenciosamente en otra operación ni descartarse como una repetición inocua. La huella ayuda a detectar la contradicción; no sustituye la autenticación del emisor.

Secuencia del laboratorio SQLite, con mensajes ya autenticados como precondición. El registro local no hace atómica una llamada posterior a Moodle.

Ver a tamaño originalCerrar

Tampoco basta con registrar «ya visto» antes de terminar el trabajo. Si el proceso cae después de esa anotación y antes de aplicar el cambio, el siguiente intento podría descartarlo como completado. El registro debe reflejar hasta dónde llegó realmente la operación.

El orden se define para una relación concreta

Para el ejemplo, la fuente podría emitir una revisión creciente por matrícula: origen, persona, edición y relación académica. La revisión de una matrícula no se compara con la de otra. Tampoco se mezclan sin acuerdo los números que asignan productores diferentes.

Si los mensajes contienen el estado completo y vigente de esa relación, un receptor puede impedir que una revisión anterior sustituya a la que ya conserva. En cambio, un mensaje que solo ordena «añadir a un grupo» puede depender de cambios previos. Saltar revisiones tiene entonces consecuencias distintas: hay que recuperar lo que falta o consultar una imagen completa del estado.

La hora de recepción no resuelve ese orden. Una fecha de creación tampoco equivale automáticamente a una secuencia inequívoca; puede tener precisión insuficiente o proceder de relojes distintos. Si el productor no ofrece una revisión adecuada, el diseño tendrá que utilizar otra forma de resolver conflictos y contrastar el estado de referencia.

El artículo de identidad en un LMS introduce la regla con un ejemplo en memoria. Aquí interesa añadir persistencia y tratar qué ocurre si el proceso se interrumpe o dos trabajadores compiten por el mismo evento.

Qué demuestra el laboratorio persistente

El laboratorio descargable utiliza SQLite y datos ficticios. Conserva el registro de eventos y una proyección local de la matrícula en una misma transacción. Se ejecuta con Python y no necesita credenciales ni realiza conexiones de red.

Incluye entregas desordenadas, duplicadas y contradictorias. También provoca un fallo antes de confirmar la transacción y repite la operación desde otra conexión. Una comprobación adicional entrega el mismo evento desde dos trabajadores y verifica que la restricción persistente impide aplicarlo dos veces en esa proyección.

Puedes consultar el resultado ejecutado. La prueba comprueba esas reglas en SQLite. Parte de mensajes que ya han superado la autenticación y no implementa un servidor de webhooks, una cola distribuida o una integración Moodle.

La llamada a Moodle introduce otra frontera

Guardar un evento y modificar una fila local dentro de la misma transacción no equivale a actualizar Moodle. Si el receptor llama a un servicio remoto, sus dos sistemas no comparten automáticamente esa transacción.

Puede ocurrir que Moodle aplique el cambio y se pierda la respuesta. Marcar entonces el evento como fallido y repetir la llamada sin comprobarla puede duplicar efectos. La recuperación de operaciones con resultado incierto explica cómo identificar el trabajo y consultar el resultado antes de decidir el siguiente intento.

La integración necesita conservar la intención de la acción pendiente, relacionarla con el evento y distinguirla de la confirmación final. La estrategia depende del contrato real del destino; un registro de entrada no convierte por sí solo todas sus operaciones en idempotentes.

Para operar el receptor observaría la antigüedad de los mensajes pendientes, los errores repetidos y las contradicciones sin resolver. Contar entregas recibidas sirve para medir tráfico, pero puede crecer por los reintentos sin que avance ninguna matrícula. Las diferencias que persistan deben poder llegar a una reconciliación con el sistema académico, con una persona responsable y una acción posible.