Triggers Reference
3 min read
Triggers are the events that wake an automation rule. This page lists all 15 triggers the engine supports, what context each one provides, and example use cases. Rules have exactly one trigger; conditions and actions then determine whether and how the rule responds.
Four triggers are order-bearing — they carry an order context, so they’re the only triggers that can use order-only conditions and order-only actions: order_placed, order_completed, refund_processed, and dispute_recorded.
Customer Lifecycle Triggers #
Score Updated #
Fires when a trust score recalculation produces a different score than before.
- Event ID:
score_updated - Context: customer hash, old score, new score, signals
- Use case: Alert when a Trusted customer drops to Caution
Segment Changed #
Fires only when the score crosses a segment boundary.
- Event ID:
segment_changed - Context: customer hash, old segment, new segment, current score
- Use case: Block customer automatically on transition to Critical
Customer Allowlisted #
Fires when a customer is added to the allowlist.
- Event ID:
customer_allowlisted - Context: customer hash, admin user, timestamp
- Use case: Sync to CRM when a customer is allowlisted as VIP
Customer Allowlist Removed #
Fires when a customer is removed from the allowlist.
- Event ID:
customer_allowlist_removed - Context: customer hash, admin user, timestamp
- Use case: Re-evaluate a customer’s standing once allowlist protection is lifted
Customer Blocked #
Fires when a customer is blocked.
- Event ID:
customer_blocked - Context: customer hash, admin user, reason
- Use case: Webhook to internal system when a customer is blocked
Customer Unblocked #
Fires when a customer is unblocked.
- Event ID:
customer_unblocked - Context: customer hash, admin user, reason
- Use case: Notify support when a previously blocked customer is reinstated
Order Lifecycle Triggers #
All four order lifecycle triggers are order-bearing — they carry an order context, so they’re the only triggers that can use order-only conditions (order_total, coupon_total, payment_method, shipping_country, billing_country, country_mismatch) and order-only actions (hold order, cancel order, require verification).
Order Placed #
Fires on every new WooCommerce order.
- Event ID:
order_placed - Context: order ID, customer hash, total, items, billing/shipping
- Use case: Hold orders from Risk/Critical customers automatically
Order Completed #
Fires when an order reaches the completed status.
- Event ID:
order_completed - Context: order ID, customer hash, total, items, billing/shipping
- Use case: Allowlist customers after a run of clean, completed orders
Refund Processed #
Fires when a refund is processed on an order.
- Event ID:
refund_processed - Context: order ID, refund amount, full or partial, customer hash
- Use case: Alert when a high-value refund pushes return rate over threshold
Dispute Recorded #
Fires when a dispute is recorded against an order.
- Event ID:
dispute_recorded - Context: order ID, customer hash, dispute details
- Use case: Flag the customer for review the moment a dispute lands on one of their orders
Detection Module Triggers #
Checkout Blocked #
Fires when TrustLens blocks a checkout attempt.
- Event ID:
checkout_blocked - Context: customer hash, reason, current score
- Use case: Notify ops when a blocked customer keeps trying to check out
Chargeback Filed #
Fires when a new chargeback is filed (auto-ingested or manually entered).
- Event ID:
chargeback_filed - Context: dispute ID, customer hash, brand, amount, reason
- Use case: Auto-block customers on first chargeback if score is low
Linked Accounts Detected #
Fires when the Linked Accounts module records a new link between customer records.
- Event ID:
linked_accounts_detected - Context: primary customer hash, linked customer hashes, fingerprint types
- Use case: Fire a webhook (e.g. to Slack) when a customer is linked to a Critical-segment account
Card Testing Attack Detected #
Fires when velocity rules trip a fingerprint lockout.
- Event ID:
card_testing_attack - Context: fingerprint hash, decline count, decline codes
- Use case: Fire a webhook to your alerting channel; tag any associated customer email for review
Shipping Anomaly Detected #
Fires when the Shipping Anomalies module fires a signal.
- Event ID:
shipping_anomaly - Context: customer hash, anomaly type (address_hopping / country_mismatch / velocity), severity
- Use case: Hold orders shipping internationally on a country mismatch + low trust score
Trigger Context Variables #
Every trigger provides a context object that conditions and actions can reference. Common variables:
| Variable | Available In |
|---|---|
customer.email_hash |
Most triggers |
customer.score |
Most triggers |
customer.segment |
Most triggers |
customer.total_orders |
Most triggers |
customer.total_disputes |
Most triggers |
order.id, order.total, etc. |
Order triggers |
dispute.brand, dispute.amount |
Dispute triggers |
fingerprint.hash |
Card-testing triggers |
See Conditions Reference for the full variable list per trigger.
Picking the Right Trigger #
Choose the most specific trigger that fits. If you want to act on chargebacks, use chargeback_filed — not score_updated filtered by “score dropped.” The specific trigger is faster, clearer, and less brittle.
Use generic triggers (like score_updated) for cross-cutting workflows where the cause matters less than the effect.
Trigger Combinations #
Rules have one trigger. To respond to multiple triggers with the same actions, create multiple rules pointing to the same outcome. The save-time validator will warn if rules collide unproductively, but the engine doesn’t prevent multiple rules firing on overlapping events.
Common pattern: a “block customer” effect achieved by three rules with triggers segment_changed (to Critical), chargeback_filed (with conditions), and linked_accounts_detected (with conditions on linked account quality). Same actions; different entry points.
