Wialon no tiene webhooks: así se hace polling

Todo arquitecto de integraciones lo pregunta en la primera semana: «¿cuál es la URL del webhook de Wialon para eventos de viaje?». No existe tal URL. Wialon no tiene un webhook de eventos de propósito general: nada registra un callback y recibe el flujo, y ninguna llamada a la API suscribe su endpoint a un elemento o a un tipo. Lo que sí existe es más acotado y funciona por regla — una notificación, una condición, una solicitud HTTP — y es la Opción B de más abajo, no un sustituto de un flujo de eventos. Todo lo que sigue es un reemplazo del webhook que usted quería, ordenado del más simple al más capaz. Elija según la latencia que necesita, no según la moda.

Por qué la ausencia es estructural y no un descuido

El modelo de eventos de Wialon está ligado a una sesión, no a un endpoint. Usted inicia sesión, le indica a la sesión qué elementos le interesan, y el servidor acumula los cambios para esa sesión hasta que usted viene a recogerlos. Nada en ese diseño tiene un lugar donde poner su URL: no hay un objeto de suscripción duradero al cual asociarla, ni una cola de entrega detrás, ni un mecanismo de reintentos que la impulse. Un webhook es una promesa de entregar más tarde; una sesión es una promesa de recordar hasta que usted pregunte.

Conviene entender esto antes de diseñar la arquitectura, porque le dice exactamente qué pueden y qué no pueden hacer las alternativas. Todo lo construido sobre la sesión hereda la vida de la sesión: cinco minutos de inactividad y desaparece. Todo lo construido sobre notificaciones hereda la forma de la notificación: una regla, una condición, disparar y olvidar. El push duradero de verdad tiene que venir de una plataforma construida con una cola de entrega, que es la tercera opción y la única que cuesta un segundo sistema.

Opción A: polling de avl_evts (segundos de latencia, sin configuración)

La sesión que ya tiene abierta puede informar sus propios cambios. Suscríbase con core/update_data_flags y luego haga polling del canal avl_evts: como máximo 10 solicitudes cada 10 segundos por sesión, en una sesión que no haga nada más. avl_evts es una ruta propia, {host}/avl_evts?sid=<sid>, no un svc contra ajax.html; w.events() del ejemplo la encapsula:

w.call("core/update_data_flags", {
    "spec": [{"type": "type", "data": "avl_unit", "flags": 1, "mode": 0}],
})
while True:
    for e in w.events().get("events", []):
        queue.put(e)  # queue, never process inline
    time.sleep(1)

Qué ve. Mensajes nuevos del hardware, ediciones de propiedades hechas en la interfaz o por otra integración, y eliminaciones. Cada evento nombra el elemento y el tipo de cambio, y la respuesta trae el reloj del servidor: use ese y no el suyo, para que una máquina con el reloj desfasado no produzca eventos que parecen llegar antes de haber ocurrido.

Qué no ve. El historial. avl_evts parte del momento en que usted se suscribió, así que un reinicio es un hueco a menos que algo más lo llene. Ese algo es una lectura por lotes de messages/load_interval para el intervalo en que su proceso estuvo caído, y el hecho de que de todos modos la necesite es el argumento más fuerte para construir primero la ruta por lotes y después la de eventos.

Cómo falla. De tres maneras, y vale la pena escribir código contra las tres antes del primer despliegue. La sesión muere tras cinco minutos de inactividad, de modo que un bucle que se detiene — una pausa larga del GC, una cola bloqueada, un despliegue — vuelve con el error 1, y la respuesta es un nuevo inicio de sesión y una nueva suscripción, no un bucle de reintentos. La suscripción se reemplaza en vez de fusionarse cuando mode es 0, lo cual es una ventaja: volver a suscribirse tras una reconexión es una única llamada idempotente en lugar de un cálculo de diferencias. Y el techo de diez por diez segundos es un presupuesto completo, así que esta sesión no debe hacer nada más: una extracción que la comparta empezará a recibir el error 10 en el peor momento posible.

Cuándo es la opción correcta. Una cuenta, un proceso, latencia medida en segundos y un operador que tolera un hueco tras un reinicio. Eso cubre la mayoría de los tableros y de las alertas.

Opción B: acciones de notificación (minutos de latencia, del lado del servidor)

Las notificaciones de Wialon pueden hacer más que enviarle un correo a un despachador. Una acción de notificación puede disparar una solicitud HTTP a una URL que usted controla cuando se cumple su condición de activación: entrada a una geocerca, exceso de velocidad, valor de un sensor, mensaje del conductor. Es lo más parecido a un webhook que tiene Wialon, y tratarlo como tal genera cuatro problemas concretos.

1. Funciona por regla, no como flujo de eventos. Se configura una notificación por condición y por recurso. Diez condiciones son diez notificaciones, cada una mantenida en la interfaz o con resource/update_notification (vea la referencia de notificaciones). No existe una regla «envíame todo», y armar una con cuarenta reglas estrechas produce una superficie de configuración que nadie va a querer mantener dentro de un año.
2. La entrega no tiene garantía documentada. Wialon no publica una política de reintentos para una solicitud que su endpoint rechaza, así que diseñe para entrega como máximo una vez: haga el endpoint idempotente y concilie contra la API, de forma programada, todo lo que no pueda permitirse perder.
3. Los payloads son plantillas, no esquemas. Usted da formato a la solicitud con macros en lugar de recibir un objeto tipado. Versiónela usted mismo: ponga un marcador de versión en la ruta de la URL para que, el día que cambie el significado de una macro, pueda distinguir el tráfico viejo del nuevo sin adivinar.
4. Nada firma la solicitud. No hay un encabezado con secreto compartido ni una firma que verificar, así que su endpoint debe autenticar a quien llama de otra manera: un componente largo y aleatorio en la ruta, una lista de direcciones de origen permitidas, o ambas. Un endpoint sin autenticación que acepta «el vehículo 14 entró al depósito» es un endpoint al que cualquiera que conozca la URL puede mentirle.

Hay además una sutileza de tiempos que sorprende a mucha gente: una notificación tiene dos capas de tiempo independientes — la condición propia del disparador y el calendario que dice cuándo está activa la regla — y ambas deben cumplirse antes de que algo se dispare. Una regla que parece correcta y nunca se dispara suele ser una regla cuyo calendario excluye las horas en que la flota realmente circula.

Úsela cuando el volumen de eventos es bajo y cada evento importa por separado: botón de alarma presionado, geocerca violada, temperatura fuera de rango. No la use como un torrente de datos: cientos de eventos de exceso de velocidad por hora a través de llamadas HTTP por regla es la forma de construir un sistema distribuido a partir de un panel de notificaciones.

Opción C: puente con flespi (push real, segunda plataforma)

Cuando necesita push genuino de servidor a servidor — flujos persistentes, enrutamiento por canales, traducción de protocolos — la respuesta no está en Wialon en absoluto. flespi acepta los mismos rastreadores, expone suscripciones de streaming reales con una cola de entrega detrás, y convive con Wialon sobre el mismo hardware: el dispositivo envía a un canal de flespi, y flespi retransmite a Wialon en el protocolo propio de Wialon, de modo que las pantallas del gestor de flota siguen funcionando mientras su plataforma recibe un flujo.

Esa es la arquitectura, y su costo es una decisión de fronteras. Dos plataformas que guardan la misma telemetría discreparán la primera vez que una de ellas no esté disponible, así que cada clase de dato necesita exactamente un dueño: los mensajes crudos del dispositivo pertenecen al lado de streaming, mientras que las unidades, geocercas, conductores y todo lo que edita un operador pertenecen a Wialon. Escriba esa tabla antes de reapuntar el primer dispositivo; la guía de arquitectura dual-stack es el tratamiento completo.

Esta es la respuesta empresarial y cuesta una segunda plataforma: una suscripción, una topología de canales y alguien que entienda ambos lados. No recurra a ella cuando la Opción A bastaría.

Cuál elegir, en una tabla

El error más común es elegir B para la cuarta fila: las notificaciones no son un mecanismo de sincronización. El historial se mueve por lotes, de forma programada, con extracción segura frente a los límites de tasa hacia su propia base de datos. Los eventos le dicen que algo ocurrió; la base de datos le dice todo lo que ocurrió. Construya ambos y no confunda ninguno.

La latencia que realmente puede prometer

Antes de elegir, calcule el costo de la ruta completa y no solo del transporte. Un rastreador reporta con su propio intervalo — habitualmente decenas de segundos en movimiento y minutos estacionado, configurable por dispositivo. Todo lo que construya encima hereda ese piso. Un bucle de avl_evts de un segundo sobre hardware que reporta cada sesenta es un bucle de un segundo que entrega una verdad de hace sesenta segundos, y ninguna ingeniería de plataforma cambia eso.

Esto importa tanto comercial como técnicamente. Un «seguimiento en tiempo real» vendido frente a una expectativa de latencia propia de un navegador GPS fallará en las pruebas de aceptación sin importar qué opción haya elegido. Escriba el intervalo de reporte del dispositivo en la especificación junto a la latencia de entrega, y la conversación pasa a ser aritmética en lugar de decepción.

Tres fallas contra las que diseñar, elija lo que elija

Duplicados. Toda opción puede entregar dos veces el mismo evento lógico: un lote reintentado, una nueva suscripción que reproduce, una notificación disparada por dos reglas superpuestas. Dé a cada evento una clave natural (id del elemento más marca de tiempo del servidor más tipo de evento) y haga idempotente al consumidor. Son cinco líneas de código al principio y un proyecto de limpieza de datos después.

Huecos. Toda opción puede perder eventos: la sesión murió, el endpoint estaba caído, el canal se reconfiguró. La única defensa real es una lectura por lotes programada que se superponga con la ruta en vivo: ejecútela sobre una ventana más amplia que su peor caída y deje que la idempotencia absorba la superposición.

Orden. Nada de lo anterior promete orden entre elementos distintos, y una máquina de estados dirigida por eventos que asuma «salida antes que llegada» terminará viéndolos invertidos. Ordene por la marca de tiempo del servidor dentro de una unidad, y nunca suponga nada sobre la relación entre dos unidades.

Qué construir sea cual sea la opción

Un proceso de conciliación. Una vez por noche, compare conteos y agregados clave entre Wialon y aquello que usted alimentó — mensajes por unidad, viajes por unidad, eventos por regla — y alerte cuando la diferencia supere un umbral que usted haya elegido deliberadamente. Sin él, una integración detenida es indistinguible de una semana tranquila, y usted se entera en el cierre de mes y no la mañana en que se rompió.

Si la elección anterior se está convirtiendo en arquitectura y no en un script, de eso se encarga la práctica de integración: diseño de eventos, garantías de entrega y conciliación, cotizados antes de construir nada.