Motor: Determinístico (sin LLM)
1. Qué hace
Te avisa cuando un indicador del panel cruza un límite que definiste — por correo electrónico, WhatsApp o webhook hacia tu propio sistema. También permite hacer un backtest de la regla antes de activarla, para saber si te va a llenar de avisos o si nunca se va a disparar.
2. ¿Determinístico o LLM?
100% determinístico. No hay LLM. La evaluación de la condición, el texto del motivo, la idempotencia y el webhook son código puro: evaluación de la regla, simulación (backtest), idempotencia/historial de disparos y envío firmado del webhook.
Condiciones soportadas: >, >=, <, <= (umbral absoluto) y drop_pct/spike_pct
(caída/alza porcentual vs. el snapshot anterior). Las series se resumen por suma/promedio/
máx/mín/último antes de la comparación. Hay cooloff (ventana mínima entre disparos) y rearme
por transición (la alerta solo se repite después de normalizarse).
3. Datos enviados y egress
- Para evaluar: nada sale — la comparación es local sobre el snapshot.
- En el webhook de salida, sale un POST hacia la URL de TU sistema con el payload de la alerta
(dashboard/widget, regla, valor, umbral, motivo,
firedAt,idempotencyKey). Eso es egress hacia ti, bajo tu control — no hacia un LLM.
4. Privacidad y retención
- Cada disparo se convierte en un evento de alerta acotado por workspace (nunca se filtra entre workspaces),
con estado de entrega (
fired/delivered/failed). - El webhook está firmado con HMAC-SHA256 (
X-Ingestia-Signature,X-Ingestia-Timestamp). El secreto se deriva por workspace (no existe en la base de datos) y es rotable cambiando la variable de entorno del secreto del webhook + redeploy. La filtración del secreto de un workspace no compromete a los demás.
5. Tokens, costo y presupuesto
No aplica — determinístico, costo de IA cero.
6. Cómo activarlo, quién puede usarlo y cómo desactivarlo
- Se configura por widget (
config.alert), con el canal y el destino que tú elijas. - El webhook exige una URL válida que pase la guarda SSRF (ver abajo).
- Rotar el secreto del webhook = cambiar el secreto del webhook (la UI muestra el valor nuevo para que lo vuelvas a pegar en tu sistema).
7. Rechazos y protecciones
- Guarda SSRF en el webhook: solo https, sin credenciales en la URL, sin
localhost/dominio interno, sin IP privada/loopback/link-local/metadata (IPv4 e IPv6, incluidas las formas decimales/hex normalizadas). El POST sale de nuestra red, así que un destino interno se bloquea. - Idempotencia a prueba de carreras: la clave es
hash(dashboardId, widgetId, hash de la regla, refreshedAt del snapshot), conUNIQUEen la base de datos — el mismo snapshot nunca dispara la misma regla dos veces, incluso con un refresh reprocesado, carrera de crons o reintento. - Regla porcentual sin base (primer refresh, sin snapshot anterior) → no se dispara (no hay comparación).
- Entrega con reintento: 3 intentos con backoff; 4xx (≠ 408/429) es permanente (no
reintenta una URL equivocada); la falla final marca el evento como
failed.
8. Limitaciones y ausencia de causalidad
- La alerta dice que se cruzó un límite, no por qué. El motivo, en portugués, describe
lo que se midió (ej.:
"Receita" caiu 32% vs snapshot anterior (150→102), limite 20%) — no afirma una causa. - El backtest es el techo de ruido: cuenta en cuántos puntos se cumpliría la condición, sin simular rearme/cooloff (que solo reducen los envíos). Y vale el aviso de siempre: pasado ≠ futuro.
- Las alertas dependen del snapshot; sin un refresh nuevo, no hay reevaluación.
9. Cómo validar
- Idempotencia: con dos refreshes del mismo snapshot, confirma que la misma regla se dispara una sola vez (el segundo se descarta).
- Guarda SSRF: registra un webhook con una URL interna/
http/con credencial y confirma que se rechaza; solo se aceptahttpshacia un destino externo. - Backtest fiel a producción: ejecuta el backtest de la regla y verifica que el conteo de disparos simulados usa la misma condición que la evaluación en vivo.
- Verificación del lado del cliente: usa el snippet de verificación proporcionado para comprobar la
firma HMAC antes de confiar en el cuerpo, y deduplica por
idempotencyKey.