---
title: Hooks and Filters Reference
description: TrustLens exposes WordPress action and filter hooks for developers building integrations or extending the plugin. This page is the verified reference — every hook listed here is present in the shipped codebase with the exact signature shown. Use it to…
url: "https://webstepper.io/docs/trustlens/developer-documentation/trustlens-hooks-and-filters/"
updated: "2026-10-18"
category: Developer Documentation
---

# Hooks and Filters Reference

TrustLens exposes WordPress action and filter hooks for developers building integrations or extending the plugin. This page is the verified reference — every hook listed here is present in the shipped codebase with the exact signature shown. Use it to drive integrations rather than guessing names from convention.

---

## Actions — Customer Lifecycle

### trustlens/score_updated

Fires after a customer's trust score is recalculated and persisted — on every recalculation, even when the score didn't change.

```
do_action( 'trustlens/score_updated', $email_hash, $new_score, $new_segment );
```

### trustlens/segment_changed

Fires only when the segment actually transitions.

```
do_action( 'trustlens/segment_changed', $email_hash, $new_segment, $old_segment, $score );
```

### trustlens/customer_blocked

Fires when a customer is marked as blocked.

```
do_action( 'trustlens/customer_blocked', $email_hash, $reason );
```

### trustlens/customer_unblocked

```
do_action( 'trustlens/customer_unblocked', $email_hash );
```

### trustlens/customer_allowlisted

```
do_action( 'trustlens/customer_allowlisted', $email_hash );
```

### trustlens/customer_allowlist_removed

```
do_action( 'trustlens/customer_allowlist_removed', $email_hash );
```

### trustlens/customer_deleted

Fires after a customer's TrustLens data has been removed.

```
do_action( 'trustlens/customer_deleted', $email_hash );
```

---

## Actions — Scoring & Events

### trustlens/calculate_score

Triggered to enqueue / perform a score recalculation. This is also the Action Scheduler hook name you filter to under **WooCommerce → Status → Scheduled Actions** when a recalculation is queued.

```
do_action( 'trustlens/calculate_score', $email_hash );
```

### trustlens/event_logged

Fires after a new row is written to the events table.

```
do_action( 'trustlens/event_logged', $email_hash, $event_type, $event_data );
```

---

## Actions — Detection

### trustlens/linked_accounts_detected

Fires when the linked-accounts check finds at least one linked account for a customer — after each order placed through checkout and when Historical Sync rebuilds the customer's fingerprints, so it repeats while links remain. The third argument is the full linked-account dataset, not just the type list. From 1.3.23 the stored `linked_count` (and `linked_accounts`) of the customer and of each linked account is updated before this fires.

```
do_action( 'trustlens/linked_accounts_detected', $email_hash, $linked_hashes, $linked );
```

### trustlens/shipping_anomaly

Fires when the Shipping Anomalies module records a new anomaly. `$score` is the (negative) penalty applied; `$reasons` is an array of reason strings.

```
do_action( 'trustlens/shipping_anomaly', $email_hash, $score, $reasons );
```

### trustlens/card_testing/attack_detected

Fires when a fingerprint is newly targeted by card-testing velocity detection. This is the hook automation rules and alert dispatchers subscribe to for the Card Testing Attack trigger.

```
do_action( 'trustlens/card_testing/attack_detected', $fingerprint_hash, $ctx );
```

### trustlens/card_testing/challenge_failed

Fires when a checkout is rejected because the browser challenge (Turnstile) was missing or failed. `$reason_code` is `challenge_missing` or `challenge_failed`. This is the hook behind the Challenge Failed automation trigger.

```
do_action( 'trustlens/card_testing/challenge_failed', $reason_code, $ctx );
```

### trustlens/card_testing/auto_escalated

Pro. Fires when Auto-Escalation triggers a Panic Freeze after a burst of attacks.

```
do_action( 'trustlens/card_testing/auto_escalated', $duration_seconds, $attack_counter );
```

### trustlens/dispute_recorded

Fires when a dispute/chargeback is recorded — Stripe / WooPayments ingestion or manual entry.

```
do_action( 'trustlens/dispute_recorded', $email_hash, $order_id, $data );
```

### trustlens/chargeback_filed

Companion notification event; fires immediately after `dispute_recorded`. Carries only the email hash.

```
do_action( 'trustlens/chargeback_filed', $email_hash );
```

---

## Actions — Checkout & Gate

### trustlens/order_placed

Fires once when an order is placed through the classic or block checkout — after the order is saved, before payment. Retrying a failed payment on the same order doesn't fire it again; orders created in the admin or via the REST API never fire it. This is the hook behind the Order Placed automation trigger.

```
do_action( 'trustlens/order_placed', $order );
```

### trustlens/gate_evaluated

Fires after the Request Gate evaluates a checkout attempt, whether or not it was blocked. `$block` is a `TrustLens_Gate_Block` object when the request was blocked, or `null` when it passed.

```
do_action( 'trustlens/gate_evaluated', $ctx, $block );
```

### trustlens/checkout_blocked

Fires when a blocked customer attempts checkout (email blocklist, or the card-testing velocity bridge). Carries the email hash and the raw email.

```
do_action( 'trustlens/checkout_blocked', $email_hash, $email );
```

### trustlens/panic_button_activated

Fires when Panic Freeze is activated (manual or auto). Carries the freeze duration in seconds.

```
do_action( 'trustlens/panic_button_activated', $duration );
```

### trustlens/payment_gateways_restricted

Pro. Fires when Payment Method Risk Controls remove one or more gateways at checkout.

```
do_action( 'trustlens/payment_gateways_restricted', $email_hash, $removed_gateways, $customer, $context );
```

---

## Actions — Automation, Admin UI & Plugin Lifecycle

### trustlens/register_modules

Fires during init for detection-module registration. Receives the main TrustLens plugin instance; call `$trustlens->register_module( $module )` to add a custom module.

```
do_action( 'trustlens/register_modules', $trustlens );
```

### trustlens/automation_triggered

Pro. Fires each time a row is written to the automation log — not only on success or failure. `$status` is `ok`, `error`, `skipped` (conditions not met or cooldown; `$error` holds the reason) or `queued` (a webhook handed to Action Scheduler, or from 1.3.23 an order hold waiting for payment). Filter on `$status` if you only want completed actions. Note the full seven-argument signature.

```
do_action( 'trustlens/automation_triggered', $email_hash, $rule, $action, $order_id, $status, $duration_ms, $error );
```

### trustlens/bulk_action_completed

Fires after a Customers-list bulk action finishes processing.

```
do_action( 'trustlens/bulk_action_completed', $action, $email_hashes, $results, $extra );
```

### trustlens/customer_profile_actions

Fires while rendering the action area on the Customer Detail profile screen. Lets extensions add custom buttons.

```
do_action( 'trustlens/customer_profile_actions', $customer );
```

### trustlens/order_metabox_actions

Fires while rendering the TrustLens meta box on the order edit screen. Lets extensions add custom action buttons. Argument order is customer, then email hash.

```
do_action( 'trustlens/order_metabox_actions', $customer, $email_hash );
```

### trustlens/sync_completed

Fires when a historical sync run finishes. Receives the sync status array.

```
do_action( 'trustlens/sync_completed', $status );
```

### wstl_fs_loaded

Fires once the Freemius SDK instance is loaded. Use it to safely call Freemius APIs from your own code.

```
do_action( 'wstl_fs_loaded' );
```

---

## Filters — Scoring

### trustlens/trust_score

Modify the final trust score after clamping.

```
$score = apply_filters( 'trustlens/trust_score', $score, $email_hash, $signals );
```

### trustlens/score_signals

Modify the signals array before summing.

```
$signals = apply_filters( 'trustlens/score_signals', $signals, $email_hash );
```

### trustlens/segment_thresholds

Customize score-to-segment mapping (segment => minimum score). The single filtered argument is the current map — the defaults below, merged with any stored `trustlens_segment_thresholds` option. A partial return is filled in from the defaults.

```
$thresholds = apply_filters( 'trustlens/segment_thresholds', array(
    'vip' => 90, 'trusted' => 70, 'normal' => 50,
    'caution' => 30, 'risk' => 10, 'critical' => 0,
) );
```

### trustlens/skip_thin_data_scoring

Decide whether a customer below the Full-confidence Order Threshold (`trustlens_min_orders`, default 3) gets thin-data scoring. While it's `true` (the default under the threshold), only the Returns module, linked-account signal and account-age bonus count; return `false` to run every module. Receives the customer row.

```
$thin_data = apply_filters( 'trustlens/skip_thin_data_scoring', $thin_data, $customer );
```

### trustlens/is_first_order_coupon

Decide whether a coupon counts as a first-order coupon for the Coupon Abuse module. The default is a heuristic: a code containing first, welcome, new, newcustomer, signup or register, or a per-user usage limit of 1. Receives the `WC_Coupon`.

```
$is_first_order = apply_filters( 'trustlens/is_first_order_coupon', $is_first_order, $coupon );
```

### trustlens/chargeback_thresholds

New in 1.3.23. Change the card-network lines the chargeback ratios are compared against — for example to raise the Visa line to 2.2% for a store in Visa's CEMEA region. Each entry needs a `brand`, a `ratio` between 0 and 1, and an optional `label`; malformed entries (no brand, ratio of 0 or less) are dropped, and a non-array return is ignored.

```
$thresholds = apply_filters( 'trustlens/chargeback_thresholds', array(
    'visa_vamp' => array( 'brand' => 'visa',       'ratio' => 0.015, 'label' => 'Visa VAMP' ),
    'mc_ecp'    => array( 'brand' => 'mastercard', 'ratio' => 0.015, 'label' => 'Mastercard ECP' ),
    'amex'      => array( 'brand' => 'amex',       'ratio' => 0.01,  'label' => 'Amex Excessive Disputes' ),
    'discover'  => array( 'brand' => 'discover',   'ratio' => 0.01,  'label' => 'Discover Excessive Disputes' ),
) );
```

---

## Filters — Pro & Integration

### trustlens/is_pro_active

Fallback that unlocks Pro features when no Freemius license is active. Useful for testing Pro behavior on a development copy of the Pro build — it can't add Pro code to the WordPress.org build, which ships without it.

```
$is_pro = apply_filters( 'trustlens/is_pro_active', false );
```

### trustlens/trust_proxy_headers

Controls whether proxy-forwarded headers (e.g. `X-Forwarded-For`) are trusted for client IP resolution. Off by default; enable only when behind a known proxy/CDN. The second argument is the direct remote address.

```
$trust = apply_filters( 'trustlens/trust_proxy_headers', false, $remote_addr );
```

### trustlens/automation/rule_cooldown

Pro. Override the cooldown window (default `HOUR_IN_SECONDS`) during which the same rule won't run again for the same customer. Applies to customer-level actions only; order actions have no cooldown. Return 0 to disable it. Receives the rule array as the second argument, so you can vary it per rule — the rule editor has no cooldown field.

```
$seconds = apply_filters( 'trustlens/automation/rule_cooldown', HOUR_IN_SECONDS, $rule );
```

### trustlens/automation/webhook_secret

Pro. Override the HMAC signing secret for an outgoing automation webhook (default: the auto-generated `trustlens_automation_webhook_secret` option). Return an empty string to send unsigned. Receives the rule array as the second argument.

```
$secret = apply_filters( 'trustlens/automation/webhook_secret', $secret, $rule );
```

### trustlens/automation/retention_days

Pro. Customize how long automation log entries are retained (default 90, clamped to 7–365 days).

```
$days = apply_filters( 'trustlens/automation/retention_days', 90 );
```

### trustlens/card_testing/panic_max_duration

Override the Panic Freeze maximum-duration ceiling. The server caps freezes at 1800 seconds (30 minutes) by default; raise or lower the ceiling with this filter.

```
$seconds = apply_filters( 'trustlens/card_testing/panic_max_duration', 1800 );
```

### trustlens_upgrade_fallback_url

Override the fallback upgrade URL used when no Freemius checkout URL is available.

```
$url = apply_filters( 'trustlens_upgrade_fallback_url', 'https://webstepper.io/wordpress/plugins/trustlens' );
```

---

## Hook Priority Conventions

TrustLens registers its hooks at a range of priorities — most at the default 10, others earlier or later (the automation engine, for example, listens to `trustlens/order_placed` at 50 and to `trustlens/score_updated` at 20). Check the registration you want to run around, then pick a lower priority to run before it:

```
add_action( 'woocommerce_order_refunded', 'my_handler', 5, 2 );
```

Or a higher one to run after:

```
add_action( 'trustlens/score_updated', 'my_post_processing', 30, 3 );
```

---

## Example: Custom Trust Score Override

```
add_filter( 'trustlens/trust_score', function( $score, $email_hash, $signals ) {
    $customer = wstl_get_customer( $email_hash );
    if ( $customer && my_loyalty_is_gold_member( $customer->customer_email ) ) {
        return min( 100, $score + 10 );
    }
    return $score;
}, 10, 3 );
```

---

## Example: Adding a Custom Signal

```
add_filter( 'trustlens/score_signals', function( $signals, $email_hash ) {
    $external_risk = my_fraud_api_get_risk( $email_hash );
    if ( $external_risk > 0.8 ) {
        $signals[] = array(
            'module' => 'external_fraud_api',
            'score'  => -20,
            'reason' => 'External fraud API risk score > 0.8',
        );
    }
    return $signals;
}, 10, 2 );
```

---

## Example: Reacting to Score Updates

```
add_action( 'trustlens/score_updated', function( $email_hash, $score, $segment ) {
    if ( $segment === 'vip' ) {
        my_crm_update_customer_tier( $email_hash, 'vip' );
    }
}, 10, 3 );
```

---

## Helper Functions

Public functions defined in `includes/functions.php` — safe for use in custom code.

| Function | Description |
| --- | --- |
| `wstl_get_email_hash( $email )` | Compute keyed HMAC-SHA256 hash of an email |
| `wstl_get_customer( $email_hash )` | Get the customer record object |
| `wstl_get_segment_from_score( $score )` | Map score to segment string |
| `wstl_log_event( $email_hash, $event_type, $event_data = array(), $order_id = null )` | Append to event log |
| `wstl_queue_score_update( $email_hash, $delay = 60 )` | Queue async score recalculation (deduplicated) |
| `wstl_block_customer( $email_hash, $reason = '' )` | Mark a customer as blocked |
| `wstl_unblock_customer( $email_hash )` | Remove block |
| `wstl_is_blocked( $email_or_hash )` | Check block state (accepts an email or a hash) |
| `wstl_allowlist_customer( $email_hash )` | Add to allowlist (also clears block and review flag, sets score 100 / VIP) |
| `wstl_remove_from_allowlist( $email_hash )` | Remove from allowlist and queue a recalculation |

The scoring engine itself is the `TrustLens_Score_Calculator` class — instantiate it directly for low-level scoring operations rather than calling a procedural helper.

---

## Stability and Versioning

Documented hooks are part of TrustLens's public API. Breaking changes are documented in the changelog and happen only on major version bumps. Newly-added hooks ship in minor releases.

Internal hooks not listed on this page may exist in the codebase but are not part of the public contract and can change without notice. If you need a hook that isn't documented here, file a feature request rather than relying on an internal one.
