Custom alert rules

When no built-in rule watches the thing you care about, create your own.

Page: Admin -> Notifications -> Custom rules · Role required: admin

Pick a rule type

Type	Use it when	Example
Clone a built-in rule	You want the same logic with a different threshold	Forecast accuracy drift at 5 percent instead of 10
Metric watcher	You want to watch a metric with your own comparator	Weekly overtime greater than 45 hours
Raw SQL alert	The condition needs a query against your warehouse	Any store with three consecutive days of negative variance

Try clone first. It reuses an existing evaluator and is a one-step change.

Fields every rule needs

Field	Notes
Key	Stable, lowercase, dot-separated, unique in the organization. org.<who>.<what> works well
Display name	Shown in the bell, settings, and admin tabs
Description	One line: what it means and what to do about it
Severity	info, warn, or critical. Reserve critical for act-now alerts
Schedule	Cron in UTC. The dialog offers presets: every 5 min, 15 min, hourly, daily, weekly
Default channels	Always include in-app so the bell shows it

Recipe: tighter forecast accuracy drift (clone)

1. Admin -> Notifications -> Custom rules -> New custom rule.
2. Choose Clone a built-in rule.
3. Base rule: Forecast accuracy drift.
4. Click Reset to the rule's built-in defaults to copy in the original thresholds.
5. In the thresholds JSON, change "drift_pct": 10 to "drift_pct": 5.
6. Set severity to critical if it warrants paging.
7. Review the preview line, then Confirm and create.

Threshold keys you will see

Key	Meaning
drift_pct	MAPE drift in percentage points
threshold_pct	Generic percent gap
threshold_hours	Hours threshold, for example weekly overtime
min_hours	Alert when hours fall below this
max_hours	Alert when hours rise above this
cooldown_minutes	Suppress repeats for this many minutes

Whatever you write is merged over the base rule's defaults, so only include the keys you are changing.

Recipe: weekly overtime over 45 hours (metric watcher)

1. New custom rule -> Metric watcher.
2. Metric: Weekly overtime.
3. Comparator: greater than.
4. Threshold: 45, or click the preset.
5. Schedule: weekly Monday (0 9 * * 1).
6. Severity warn, channels in-app and email.
7. Confirm and create. The preview reads "Alert when Weekly overtime > 45h".

Recipe: sales pacing 20 percent behind (metric watcher)

1. Metric: Sales pacing gap. The value is signed; negative means behind.
2. Comparator: less than.
3. Threshold: -20.
4. Schedule: every 15 minutes during the operating day.
5. Severity critical, channels in-app and Slack so the manager sees it on shift.

Available metrics

Metric	Unit	Meaning
MAPE (rolling 30d)	%	Mean absolute percent error of forecast against actuals. Lower is better; 5 to 25 is typical
Bias (rolling 30d)	%	Signed average error. Positive means the forecast runs low
Labor hours pacing	%	Actual labor hours against the demand-based plan. 100 percent is on plan
Sales pacing gap	%	Today's actual sales against the forecasted pace. Negative is behind
Weekly overtime	h	Hours per employee per week beyond the overtime threshold

The dialog offers presets per metric, such as Tight (10%), Default (15%), and Loose (25%).

Raw SQL alerts

1. New custom rule -> Raw SQL alert.
2. Write a read-only query that returns one row per location that should alert.
3. Click Test SQL. The panel reports Would trigger or Would not trigger so you can validate before saving.
4. Set the schedule, severity, and channels, then create.

Queries are validated as read-only and scoped to your organization before they run.

After creating

A custom rule behaves like a built-in one:

• it appears under Custom alerts in /settings/notifications,
• it shows up in role defaults and org overrides immediately,
• an admin can enforce its channels,
• it is evaluated on its schedule.

Turning a rule off

Disabling a custom rule takes effect immediately: its scheduler job is removed, it disappears from org overrides, role defaults, and user settings, and it stays in the Custom rules panel badged Disabled so you can switch it back on later.

If a rule does not fire

1. Org overrides - make sure it is not set to Off for everyone.
2. Custom rules - make sure the rule itself is enabled.
3. Delivery Health - look for delivery failures, see Notifications overview.
4. Confirm the underlying metric actually has data, for example accuracy metrics need actuals.