Actions Reference
7 min read
Actions are what a rule does when its trigger fires and its conditions pass. Each rule can have one or more actions, executed in the order listed. Actions run asynchronously through a dispatcher with automatic retry on failure. This page documents every available action, what it does, and how to configure it.
The Ten Actions #
| Action | Effect |
|---|---|
| Send email | Dispatches a configurable email to one or more recipients |
| Add note | Adds an internal note to the customer’s record |
| Add tag | Adds a string tag to the customer’s record for downstream filtering |
| Block customer | Sets is_blocked = true on the target customer |
| Allowlist customer | Adds the customer to the allowlist; locks score at 100 |
| Flag for review | Flags the customer for manual review |
| Fire webhook | POSTs a signed JSON payload to a configured URL |
| Hold order (order-bearing trigger only) | Sets the order status to on-hold |
| Cancel order (order-bearing trigger only) | Sets the order status to cancelled |
| Require verification (order-bearing trigger only) | Requires the customer to complete additional verification on the order |
The three order-bearing actions — Hold order, Cancel order, and Require verification — act on an order, so they’re only available with an order-bearing trigger (order_placed, order_completed, refund_processed, or dispute_recorded). Note that “Add tag” is the same action as the tag-customer action described below — it isn’t counted twice.
There is no dedicated Slack action. To reach Slack, point the Fire webhook action at a Slack incoming webhook URL.
Block Customer #
Sets the customer’s is_blocked flag to true. If the global checkout-blocking master toggle is on, the customer cannot complete checkout. The action is logged in the customer’s event timeline with attribution to the rule that triggered it.
Parameters:
reason— text logged in the audit trail (default: “Auto-blocked by rule {rule_name}”)
Idempotent: Yes. Re-blocking an already-blocked customer is a no-op.
Caution: If your master toggle is off, this action sets state but doesn’t enforce. The customer can still check out. To fully act, ensure global enforcement is on.
Allowlist Customer #
Sets the customer’s is_allowlisted flag to true. Score is locked at 100; segment becomes VIP. All future negative signals are suppressed for this customer until they’re removed from the allowlist.
Parameters:
reason— text logged in the audit trail
Use case: Auto-allowlist customers who hit a positive milestone — e.g. “20 completed orders, no signals” — to lock in their VIP status.
Hold Order #
Sets the order status to on-hold. The customer’s order isn’t cancelled, but it doesn’t proceed to fulfillment until an admin reviews and changes the status. WooCommerce’s standard on-hold semantics apply: payment isn’t captured if not already, inventory is reserved.
Parameters:
note— internal admin note attached to the order (default: “Held by TrustLens rule {rule_name}: {condition summary}”)
Use case: “Hold orders from Risk-segment customers for manual review.”
Constraint: Only valid in order-trigger contexts (the rule must have access to an order ID).
Cancel Order #
Sets the order status to cancelled. WooCommerce’s standard cancellation flow applies — refund if needed, restore inventory, send cancellation email if configured.
Parameters:
note— internal admin noterefund— boolean; whether to attempt automatic refund (default false)
Use case: “Cancel orders from Critical-segment customers automatically; refund payment.”
Caution: Cancellation is harder to reverse than a hold. Prefer holds unless you’re confident.
Send Email #
Dispatches an email to a configured recipient list with a customizable subject and body. The body supports template variables from the trigger context (customer email, order ID, dispute amount, etc.).
Parameters:
recipients— comma-separated email addressessubject— email subject; supports template variablesbody— email body; supports template variables and basic HTMLformat— plain text or HTML (default HTML)
Template variables: {customer.email}, {customer.score}, {customer.segment}, {order.id}, {order.total}, {dispute.brand}, etc. — anything in the trigger context.
Use case: “Email the operations lead when any Risk-segment customer places a $500+ order.”
Fire Webhook #
POSTs a JSON payload to a configured URL. The payload includes the full trigger context (customer data, order data, dispute data, etc.) plus rule metadata.
Parameters:
url— destination endpointsecret— HMAC-SHA256 signing key (auto-generated if not provided)headers— optional custom headers
Security: Every webhook is signed with HMAC-SHA256. The signature is sent as the X-TrustLens-Signature header, equal to sha256= followed by hmac_sha256(timestamp + "." + body, secret). A X-TrustLens-Timestamp header carries the Unix epoch so receivers can reject replays. Receivers should verify the signature before trusting the payload. See Webhooks and HMAC.
Retry: Failed webhook deliveries retry at 60s / 120s / 240s backoff. After 3 failed retries, the action is logged as failed.
Use case: “Send a webhook to your CRM when a customer’s segment changes to VIP.”
Add Tag (Tag Customer) #
Adds a string tag to the customer’s record. Tags are useful for:
- Filtering the Customers list later (“show all customers tagged ‘manual review needed'”)
- Cross-rule communication (“once tagged, another rule can pick them up”)
- Building cohorts for export
Parameters:
tag— string labelappend— boolean; if true, adds to existing tags; if false, replaces them (default true)
Use case: “Tag customers with ‘high-value-at-risk’ when their score drops below 30 and their total order value is over $5000.”
Add Note #
Adds an internal note to the customer’s record. Unlike a tag (a short label used for filtering and cohorting), a note is free-text context for human reviewers — what happened, which rule fired, and why.
Parameters:
note— note text; supports template variables from the trigger context
Use case: “When a chargeback is filed, add a note summarizing the dispute brand, amount, and reason so reviewers have it in one place.”
Flag for Review #
Flags the customer for manual review, surfacing them in the moderation queue without blocking checkout. Use it when an event is suspicious enough to warrant a human look but not severe enough to act automatically.
Parameters:
reason— text logged with the flag (optional)
Use case: “Flag for review when a high-value order comes from a non-VIP Risk-segment customer.”
Require Verification #
Requires the customer to complete additional verification on the order before it proceeds. Use it as a middle ground between letting an order through and holding or cancelling it outright.
Parameters:
note— internal admin note attached to the order (optional)
Use case: “Require verification on first orders that ship to a country that doesn’t match the billing country.”
Constraint: Order-bearing trigger only — the rule must have access to an order (order_placed, order_completed, refund_processed, or dispute_recorded).
Multi-Action Rules #
A rule can have multiple actions. They run in the order listed:
- Tag the customer
- Hold the order
- Send an alert email
- Fire a webhook
Actions are independent — if one fails, the others still attempt. The action log shows per-action success/failure.
Async Dispatch with Retry #
All actions run through the dispatcher:
- Action is queued as an Action Scheduler job
- Job runs in the background; the triggering event doesn’t wait
- If the action fails (network error, gateway timeout), the job is rescheduled with backoff
- Backoff sequence: 60s → 120s → 240s
- After 3 failed attempts, the action is logged as failed and stops retrying
This makes the engine resilient to transient failures — a brief Slack outage doesn’t lose alerts; webhook receivers under temporary load get retried.
Failure Handling #
Failed actions are visible in the Automation Log with the failure reason. Common failure modes:
- Webhook 4xx/5xx response — receiver rejected; retry until limit reached
- Webhook timeout — 10-second timeout per attempt
- Email delivery failure — depends on WordPress mail config
- Permission error — e.g. order cancel fails if order is already cancelled
- Action-level configuration error — bad URL, invalid recipient, etc.
Review the Automation Log periodically to catch silently failing actions.
Action Idempotency #
Most actions are idempotent — running them twice produces the same end state. Block, Allowlist, Tag are idempotent. Send Email and Fire Webhook are not — each invocation produces a separate side effect. Use cooldowns on rules with non-idempotent actions to prevent duplicate side effects on rapid trigger events.
