Guide: Building Your Own Detection Rules

This section walks you through creating custom detection rules. Use the system rules above as templates and reference examples.

The Five Building Blocks

Every detection rule has five components that work together:

┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│   SOURCE    │ →  │   FILTER    │ →  │  AGGREGATE  │ →  │  EVALUATE   │ →  │ FINGERPRINT │
│             │    │             │    │             │    │             │    │             │
│ What data   │    │ Which       │    │ How to      │    │ When to     │    │ How to      │
│ to query    │    │ records     │    │ summarize   │    │ trigger     │    │ identify    │
└─────────────┘    └─────────────┘    └─────────────┘    └─────────────┘    └─────────────┘

---

Step 1: Choose Your Data Source

The source tells the rule what type of data to query from your connected system.

Available Sources by Integration:

Integration	Available Objects
Zuora	account, subscription, invoice, payment, billrun, creditmemo, usage
Stripe	customer, invoice, payment_intent, subscription, refund, dispute
Salesforce	Account, Opportunity, Lead, Contact, Case

Example from System Rules:

• Failed Bill Run Detection uses billrun from Zuora

• Dispute Rate Signal uses dispute from Stripe

• Stale Opportunity Pipeline uses Opportunity from Salesforce

---

Step 2: Add Filters

Filters narrow down which records to examine. You can combine multiple filters.

Available Operators:

Operator	Meaning	Example
=	Equals	Status equals "Error"
!=	Not equals	Status is not "Active"
>	Greater than	Amount greater than 1000
>=	Greater than or equal	Balance at least 0
<	Less than	Count less than 5
<=	Less than or equal	Age at most 30 days
in	Matches any in list	Status is "Error", "Failed", or "Canceled"
not_in	Doesn't match any	Stage is not "Closed Won" or "Closed Lost"

Examples from System Rules:

Rule	Filter Logic
Failed Bill Run Detection	Status in ["Error", "Failed", "Canceled"]
Outstanding Account Balance	Balance > 0 AND Status = "Active"
High-Value Deal at Risk	Amount > 100,000 AND IsClosed = false
Stale Opportunity Pipeline	IsClosed = false AND StageName not_in ["Closed Won", "Closed Lost"]

Tip: Use multiple filters to be precise. The Outstanding Account Balance rule uses two filters to find only active accounts with a positive balance—this avoids false signals from closed accounts.

---

Step 3: Configure Aggregation

Aggregation determines how the rule summarizes the filtered data.

Aggregation Functions:

Function	What It Does	Use When
count	Counts the number of records	You care about how many (e.g., failed payments)
sum	Adds up a numeric field	You care about total amount (e.g., refund dollars)

Time Windows:

Window	Duration	Best For
60 minutes	1 hour	Detecting sudden spikes
360 minutes	6 hours	Short-term patterns
1440 minutes	24 hours	Daily monitoring
10080 minutes	7 days	Weekly trends

Grouping Options:

Approach	Result	Use When
No grouping	One total for all records	You want overall volume (e.g., total refund amount)
Group by account	Separate count/sum per account	You want per-customer signals
Group by owner	Separate count/sum per owner	You want per-rep signals
Group by status/type	Separate count/sum per category	You want to see patterns by type

Examples from System Rules:

Rule	Function	Window	Grouped By
Failed Payment Spike	count	1 hour	Payment method type
Credit Memo Spike	sum (amount)	24 hours	Not grouped
Subscription Churn Risk	count	7 days	Account
Lead Response Time SLA	count	24 hours	Lead owner

Tip: The Failed Payment Spike rule uses a short 1-hour window and groups by payment method type—this helps you spot if a specific payment processor is having issues.

---

Step 4: Set the Evaluation Threshold

The threshold determines when the rule creates a signal.

Available Comparisons:

Operator	Meaning	Example
> or gt	Greater than	More than 10
>= or gte	Greater than or equal	1 or more
< or lt	Less than	Fewer than 5
<= or lte	Less than or equal	100 or fewer
= or eq	Equals	Exactly 0

Choosing the Right Threshold:

Scenario	Recommended Threshold
Any occurrence is a problem	>= 1 (e.g., failed bill runs)
Small numbers are normal	> 5 or > 10 (e.g., payment declines)
Large volumes are concerning	> 10,000 (e.g., usage spikes)
Dollar amounts	Set based on your business (e.g., > $5,000 refunds)

Examples from System Rules:

Rule	Threshold	Reasoning
Failed Bill Run Detection	>= 1	Any failed bill run needs attention
Failed Payment Spike	> 10 per hour	A few failures are normal; 10+ suggests a problem
High Invoice Aging	> 5 per account	Multiple aged invoices indicate collection issues
Large Refund Volume	> $5,000/day	High refund volume may signal problems

Tip: Start with a higher threshold to reduce noise, then lower it as you understand your normal patterns.

---

Step 5: Configure Fingerprinting

Fingerprinting controls how signals are grouped and deduplicated.

Fingerprint Modes:

Mode	Behavior	Use When
entity	One signal per unique record	You want to track individual items (e.g., each failed payment)
aggregate	One signal for the overall pattern	You want to track volume trends (e.g., daily refund total)

Examples from System Rules:

Rule	Mode	Fields	Result
Failed Payment Signal	entity	Account ID, Payment ID	One signal per failed payment
Credit Memo Spike	aggregate	(none)	One signal when daily total is high
Subscription Churn Risk	entity	Account ID	One signal per at-risk account
Failed Payment Spike	aggregate	Payment method type	One signal per payment type with issues

Tip: Use entity mode when each individual record needs attention. Use aggregate mode when you care about overall patterns rather than individual items.

---

Putting It All Together: A Custom Rule Example

Let's say you want to detect Zuora accounts with failed payments in the last week that have a balance over $500.

Step 1 - Source: Zuora accounts

Step 2 - Filters:

• Balance > 500

• Status = "Active"

Step 3 - Aggregation:

• Function: count

• Window: 7 days (10080 minutes)

• Group by: Account ID

Step 4 - Evaluation:

• Threshold: >= 1 (any matching account)

Step 5 - Fingerprint:

• Mode: entity

• Fields: Account ID

Result: You'll get one signal for each active account with a balance over $500, and the signals won't duplicate for the same account within the week.

---

Quick Reference: Common Rule Patterns

Pattern 1: Catch Every Occurrence

Use when: Each individual issue needs attention
Filter: Specific error condition
Aggregate: count, no grouping
Threshold: >= 1
Fingerprint: entity mode with record ID
Example: Failed Bill Run Detection

Pattern 2: Detect Volume Spikes

Use when: High volume indicates a systemic issue
Filter: Broad or no filter
Aggregate: count or sum, short time window (1-6 hours)
Threshold: High number based on your normal volume
Fingerprint: aggregate mode
Example: Failed Payment Spike, Credit Memo Spike

Pattern 3: Per-Customer Monitoring

Use when: You want signals grouped by customer/account
Filter: Problem condition
Aggregate: count, group by account/customer ID
Threshold: >= 1 or based on acceptable count
Fingerprint: entity mode with account ID
Example: Outstanding Account Balance, Failed Subscription Payment

Pattern 4: Team Performance Tracking

Use when: Monitoring by owner/rep
Filter: Condition indicating issues
Aggregate: count, group by owner ID
Threshold: Based on acceptable workload
Fingerprint: entity mode with owner ID
Example: Lead Response Time SLA, Stale Opportunity Pipeline

---

Rule Categories Explained

Category	What It Covers
Payment Health	Payment processing, failures, gateway issues
Billing Accuracy	Invoice generation, bill runs, pricing errors
Revenue Leakage	Unbilled usage, missed charges, lost revenue
Churn Risk	Cancellations, at-risk customers, retention signals
Pipeline Health	Sales opportunity progress and stale deals
Sales Efficiency	Lead response times and sales process metrics
Revenue Risk	High-value deals at risk of loss
Data Integrity	Data quality, sync issues, missing records

---

Severity Levels

Level	When to Use	Response Time
Critical	Immediate revenue or customer impact	Same day
Warning	Potential issue that needs attention	Within a few days
Info	Awareness item, no immediate action needed	Review periodically

---

Best Practices

1. Start with Critical Rules - Activate the critical severity rules first as they catch the most urgent issues

2. Link to Production Integrations - Connect rules to your production systems, not test environments

3. Monitor the System Feed - Check your feed regularly for new signals from detection rules

4. Document Your Responses - Use the signal notes feature to track what actions you've taken

5. Review Rule Performance - Periodically check if rules are generating useful signals or need adjustment