---
title: Automation Overview
description: "The Automation Rules engine is the Pro feature that lets TrustLens act on what it detects. Rules are trigger-condition-action sequences — \"when X happens, if Y is true, then do Z\" — that fire when customer risk changes, orders are…"
url: "https://webstepper.io/docs/trustlens/automation/automation-overview/"
updated: "2026-10-18"
category: Automation
---

# Automation Overview

The Automation Rules engine is the Pro feature that lets TrustLens act on what it detects. Rules are trigger-condition-action sequences — "when X happens, if Y is true, then do Z" — that fire when customer risk changes, orders are placed, refunds happen, disputes are recorded, linked accounts are detected, card-testing attacks or failed browser challenges hit checkout, shipping anomalies are spotted, or a customer is blocked, unblocked or allowlisted. Without the engine, TrustLens surfaces risk for human moderation; with it, you can build closed-loop workflows that act in seconds without admin attention.

Location: **TrustLens → Automation**. The engine is **off by default** — turn on the **Engine running** switch in the page header and click **Save** before any rule can fire.

---

## The Rule Shape

Every rule has three sections:

| Section | What It Does |
| --- | --- |
| **Trigger** | The event that wakes the rule up. One trigger per rule. Examples: "Order Placed," "Chargeback Filed," "Score Updated." |
| **Conditions** | Optional filters that must all be true for the rule to act. Multiple conditions combine with AND only — there is no OR. Leave the list empty and the rule fires on every trigger event. Examples: "trust_score < 30," "total_disputes >= 2." |
| **Action** | What the rule does when it fires. Each rule has exactly **one** action, plus one optional text value (block reason, note text, tag name, email address or webhook URL). To do two things, create two rules with the same trigger and conditions. Examples: "Block Customer," "Send Email Notification," "Send Webhook." |

Rules can be enabled or disabled independently with the **Rule is active** switch in the rule editor. Disabled rules aren't evaluated at all, so they leave nothing in the log.

---

## What's Available

| Component | Count | Details |
| --- | --- | --- |
| Triggers | 16 | See [Triggers Reference](/docs/trustlens/automation/triggers-reference/) |
| Condition fields | 46 (25 customer, 6 order-only, 15 refund-only) | See [Conditions Reference](/docs/trustlens/automation/conditions-reference/) |
| Actions | 11 (8 for any trigger, 3 for order triggers only) | See [Actions Reference](/docs/trustlens/automation/actions-reference/) |

---

## Example Rule

"When a chargeback is filed against a customer who has 2+ disputes and a trust score under 30, block the customer and alert the team."

Because a rule has one action, this takes two rules with the same trigger and conditions:

- **Trigger:** Chargeback Filed
- **Conditions:** `total_disputes >= 2` AND `trust_score < 30`
- **Rule 1 action:** Block Customer
- **Rule 2 action:** Send Webhook to a Zapier or Make URL that posts the alert into your #fraud-alerts Slack channel

Don't point Send Webhook straight at a Slack incoming-webhook URL: Slack requires a `text` field that the TrustLens payload doesn't have, so Slack rejects the request. Route it through Zapier, Make or a small endpoint that reformats the payload. See [Webhooks and HMAC](/docs/trustlens/automation/webhooks-and-hmac/).

This is a typical "tighten the noose" rule — escalate enforcement automatically when a known-risky customer crosses a new threshold.

---

## How Rules Run

When a trigger event fires, the automation engine:

1. Collects all enabled rules with that trigger
2. For each rule, evaluates the conditions against the customer's TrustLens record (plus the order on order triggers, and the refund on Refund Processed). The first condition that fails stops the rule, and a SKIP row records which one
3. If all conditions pass, runs the rule's action straight away, in the same request. Customer-level actions are limited by a one-hour cooldown per rule per customer (see below)
4. The one exception is **Send Webhook**: delivery is queued with Action Scheduler and retried up to 3 times (60s / 120s / 240s) on failure
5. From 1.3.23, Hold Order, Cancel Order and Require Verification on an order that hasn't been paid yet (an Order Placed rule) wait for the payment instead of changing the status at once — see [Actions Reference](/docs/trustlens/automation/actions-reference/)
6. Every result is logged for inspection

Only webhook delivery is asynchronous. Every other action finishes inside the request that fired the trigger, so a rule on Order Placed acts during checkout.

---

## The Save-Time Validator

When you save a rule, TrustLens validates it before accepting:

- **Known values** — the trigger, action, every condition field and every operator must be one TrustLens recognises
- **Order-only pieces** — Hold Order, Cancel Order, Require Verification and the 6 order fields need an order trigger (Order Placed, Order Completed, Refund Processed, Dispute Recorded); the 15 refund fields need Refund Processed
- **Operator and value checks** — text, segment and yes/no fields accept only `=` and `!=`; values must be possible for the field (a trust score or return rate between 0 and 100, counts of 0 or more)
- **Unsatisfiability check** — can the conditions possibly be true together? A rule with `trust_score > 80` AND `trust_score < 20` is rejected as unsatisfiable, as are combinations the data model rules out (e.g. `total_orders = 0` with `total_order_value > 0`)
- **Trigger-state contradictions** — conditions that contradict what the trigger guarantees (e.g. a Customer Blocked rule conditioned on `is_blocked = 0`) are rejected
- **Incomplete actions** — Send Webhook needs a valid URL, Add Tag and Remove Tag need a tag name, and Send Email's value must be a valid address if you fill it in

Invalid rules are rejected at save time with a specific error message. This prevents the most common failure mode of automation engines: silently-broken rules that never fire.

---

## The Rule Inspector

Click a rule in the list on the Automation page to open its inspector:

- A When → If → Then summary of the rule
- Last 7 days: times fired, succeeded, errors, skipped, average execution time, plus a 14-day sparkline
- Recent runs: the latest 10 attempts, each with time, action, order number, customer and an OK / ERR / SKIP / QUEUED badge
- SKIP and ERR rows show the reason: "Cooldown active," "Condition not met: trust_score > 50"

This is the answer to the perennial question "why didn't my rule fire?" — you can see exactly which condition rejected the event. See [Rule Inspector](/docs/trustlens/automation/rule-inspector/).

---

## Cooldowns

Customer-level actions have a fixed cooldown: the same rule fires at most once per hour for the same customer. Further matches inside that hour are logged as SKIP with "Cooldown active." This:

- Prevents alert spam when a customer triggers a rule repeatedly
- Rate-limits emails and webhook calls
- Stops an action that re-triggers its own rule (e.g. Block Customer on a Customer Blocked rule) from looping

There is no per-rule cooldown field in the rule editor. The order actions (Hold Order, Cancel Order, Require Verification, and Flag for Review on an order trigger) have no cooldown. If an action errors, its cooldown is released so the next event can try again. Developers can change the window — or set it to 0 to disable it — with the `trustlens/automation/rule_cooldown` filter, which receives the rule.

---

## Logging

Every rule evaluation and action is written to the automation log:

- Rule ID and name, trigger, action, customer hash, order ID
- Status: ok, error, skipped (with the reason) or queued (webhook waiting for delivery, or a hold waiting for payment)
- Execution time in milliseconds and the error message on failures
- For webhooks, the final result after retries — intermediate failed attempts aren't logged separately

There's no separate log screen: the Rule Inspector shows each rule's latest 10 runs and 7-day totals, and non-skipped runs also appear in the customer's Recent activity. The full log lives in the `{prefix}trustlens_automation_logs` table. Rows older than 90 days are purged daily; developers can change the window (7–365 days) with the `trustlens/automation/retention_days` filter.

---

## Common Rule Patterns

- **Escalation:** Segment Changed + segment = critical → Send Email; a second rule on Order Placed + segment = critical → Hold Order
- **Block-on-dispute:** Chargeback Filed + trust_score < 30 → Block Customer
- **VIP tagging:** Order Placed + segment = vip → Add Tag (tags the customer record, not the order)
- **Linked-account warning:** Linked Accounts Detected + linked_accounts ≥ 3 → Send Webhook to a Zapier or Make URL that posts to Slack
- **Coupon abuse mitigation:** Order Placed + coupon_then_refund ≥ 2 → Cancel Order (from 1.3.23 this waits for the payment: an unpaid order is cancelled, a paid one is held with a note)
- **Card-testing follow-up:** Card Testing Attack → Send Email Notification to your ops lead (fires only when the attempt carried a billing email)
- **High-value monitoring:** Order Placed + order_total > 1000 + segment != vip → Flag for Review (on an order trigger this flags the order)

Segment values are lowercase (`vip`, `trusted`, `normal`, `caution`, `risk`, `critical`) and matched exactly.

---

## Engine Performance

Rule evaluation is fast — typically < 5ms per rule per event. Most triggers evaluate dozens of rules without measurable impact on the triggering event's latency. Webhook delivery is queued, so a slow receiver doesn't slow down the event flow; the other actions run inline and are quick database or status updates (Send Email is as fast as your mail setup).

Stores running 50+ automation rules see no notable performance impact. The engine scales beyond that, but at some point you should think about whether your rule set has consolidation opportunities.

---

## Disabling Automation

To pause the entire engine: turn off **Engine running** in the Automation page header and click **Save**. While paused:

- No triggers are evaluated and nothing is logged
- No actions fire
- Existing rules remain saved
- Webhooks already queued still deliver, and holds already waiting for payment are still applied
- Re-enabling resumes from the next trigger event

Pausing is useful during major operational changes (migrations, new gateway integrations) where rule actions might produce noise.