Actions Reference
5 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 Seven Actions #
| Action | Effect |
|---|---|
| Block customer | Sets is_blocked = true on the target customer |
| Allowlist customer | Sets is_allowlisted = true; locks score at 100 |
| Hold order | Sets the order status to on-hold |
| Cancel order | Sets the order status to cancelled |
| Send email | Dispatches a configurable email to one or more recipients |
| Fire webhook | POSTs a JSON payload to a configured URL with HMAC signature |
| Tag customer | Adds a string tag to the customer’s record for downstream filtering |
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. 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.”
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.”
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.
