Engine: Deterministic (no LLM)
1. What it does
Notifies you when a dashboard indicator crosses a limit you defined — by email, WhatsApp, or webhook to your own system. It also lets you backtest the rule before turning it on, so you know whether it will flood you with notices or never fire.
2. Deterministic or LLM?
100% deterministic. There is no LLM. Evaluating the condition, the reason text, idempotency, and the webhook are pure code: rule evaluation, simulation (backtest), idempotency/firing history, and signed webhook delivery.
Supported conditions: >, >=, <, <= (absolute threshold) and drop_pct/spike_pct
(percentage drop/rise vs. the previous snapshot). Series are summarized by sum/average/
max/min/last before the comparison. There's a cooloff (minimum window between firings) and re-arming
on transition (the alert only repeats after things return to normal).
3. Data sent and egress
- To evaluate: nothing leaves — the comparison is local, over the snapshot.
- With the outbound webhook, a POST goes out to YOUR system's URL with the alert payload
(dashboard/widget, rule, value, threshold, reason,
firedAt,idempotencyKey). That's egress to you, under your control — not to an LLM.
4. Privacy and retention
- Each firing becomes an alert event scoped by workspace (it never leaks between workspaces),
with a delivery status (
fired/delivered/failed). - The webhook is signed with HMAC-SHA256 (
X-Ingestia-Signature,X-Ingestia-Timestamp). The secret is derived per workspace (it doesn't exist in the database) and is rotatable by bumping the webhook secret env var + redeploying. A leak of one workspace's secret doesn't compromise the others.
5. Tokens, cost, and budget
Not applicable — deterministic, zero AI cost.
6. How to turn it on, who can use it, and how to turn it off
- Configured per widget (
config.alert), with a channel and destination you choose. - The webhook requires a valid URL that passes the SSRF guard (see below).
- Rotating the webhook secret = changing the webhook secret (the UI shows the new value for you to paste back into your system).
7. Refusals and protections
- SSRF guard on the webhook: https only, no credentials in the URL, no
localhost/internal domain, no private/loopback/link-local/metadata IP (IPv4 and IPv6, including normalized decimal/hex forms). The POST leaves from our network, so internal destinations are blocked. - Race-proof idempotency: the key is
hash(dashboardId, widgetId, rule hash, snapshot refreshedAt), with aUNIQUEconstraint in the database — the same snapshot never fires the same rule twice, even with a reprocessed refresh, racing crons, or a retry. - Percentage rule with no baseline (first refresh, no previous snapshot) → doesn't fire (there's nothing to compare).
- Delivery with retry: 3 attempts with backoff; 4xx (≠ 408/429) is permanent (it doesn't
retry a wrong URL); a final failure marks the event as
failed.
8. Limitations and absence of causality
- The alert says that a limit was crossed, not why. The reason, in Portuguese, describes
what was measured (e.g.,
"Receita" caiu 32% vs snapshot anterior (150→102), limite 20%) — it doesn't claim a cause. - The backtest is the noise ceiling: it counts at how many points the condition would hold, without simulating re-arming/cooloff (which only reduce the sends). And the usual warning applies: past ≠ future.
- Alerts depend on the snapshot; without a new refresh, there's no re-evaluation.
9. How to validate
- Idempotency: with two refreshes of the same snapshot, confirm that the same rule fires only once (the second is discarded).
- SSRF guard: register a webhook with an internal/
http/credentialed URL and confirm it's rejected; onlyhttpsto an external destination is accepted. - Backtest faithful to production: run the rule's backtest and check that the count of simulated firings uses the same condition as the live evaluation.
- Verification on the customer side: use the provided verification snippet to check the
HMAC signature before trusting the body, and deduplicate by
idempotencyKey.