Saltar al contenido

Traducción automática — la versión en portugués es la referencia. Ver en portugués

Actualizado el 2026-10-04

Alertas y webhooks de salida

Avisos automáticos cuando un número del panel supera un límite, por correo electrónico, WhatsApp o una llamada a otro sistema.

En esta página (9)

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), con UNIQUE en 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 acepta https hacia 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.

Enlaces relacionados