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. 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.

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. Both the queueing layer and the worker fire on this.

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 a new account link is recorded.

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

trustlens/shipping_anomaly #

Fires when the Shipping Anomalies module records a new anomaly.

do_action( 'trustlens/shipping_anomaly', $email_hash, $anomaly_type, $details );

trustlens/chargeback_filed #

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

do_action( 'trustlens/chargeback_filed', $dispute_id, $email_hash, $data );

trustlens/dispute_recorded #

Companion event for dispute persistence; fires alongside chargeback_filed.

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

---

Actions — Checkout #

trustlens/checkout_blocked #

Fires when the Request Gate rejects a checkout request (Card-Testing lockout, customer block, Panic Freeze).

do_action( 'trustlens/checkout_blocked', $email_hash, $reason, $context );

trustlens/panic_button_activated #

Fires when Panic Freeze is activated (manual or auto).

do_action( 'trustlens/panic_button_activated', $source, $admin_user_id );

trustlens/payment_gateways_restricted #

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

do_action( 'trustlens/payment_gateways_restricted', $email_hash, $hidden_gateways, $rule_id );

---

Actions — Automation & Plugin Lifecycle #

trustlens/register_modules #

Fires during init for detection-module registration.

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

trustlens/automation_triggered #

Pro. Fires when an automation rule successfully evaluates and dispatches actions.

do_action( 'trustlens/automation_triggered', $rule_id, $trigger_type, $context );

trustlens/bulk_action_completed #

Fires after a Customers-list bulk action finishes processing.

do_action( 'trustlens/bulk_action_completed', $action, $affected_count );

trustlens/order_metabox_actions #

Fires while rendering the TrustLens meta box on the order edit screen. Lets extensions add custom action buttons.

do_action( 'trustlens/order_metabox_actions', $order, $customer );

---

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.

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

---

Filters — Pro & Integration #

trustlens/is_pro_active #

Determines whether Pro features are unlocked. Useful for testing Pro behavior on a Free instance.

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

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.

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

trustlens/automation/rule_cooldown #

Pro. Override per-rule cooldown duration.

$seconds = apply_filters( 'trustlens/automation/rule_cooldown', $seconds, $rule_id, $email_hash );

trustlens/automation/webhook_secret #

Pro. Override the HMAC signing secret for an outgoing webhook.

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

trustlens/automation/retention_days #

Pro. Customize how long automation log entries are retained.

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

trustlens/card_testing/panic_max_duration #

Override Panic Freeze maximum duration (default 900 seconds = 15 minutes).

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

---

Hook Priority Conventions #

TrustLens registers its own hooks at default priority 10. To run code before TrustLens:

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

To run after:

add_action( 'trustlens/score_updated', 'my_post_processing', 20, 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 )	Append to event log
wstl_queue_score_update( $email_hash )	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_hash )	Check block state
wstl_allowlist_customer( $email_hash )	Add to allowlist

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.