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.

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 linked accounts are detected for a customer. The third argument is the full linked-account dataset, not just the type list.

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/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/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 after an automation rule has executed (success or failure). 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. The default map is passed in as the single filtered argument.

$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', 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 per-rule cooldown window (default HOUR_IN_SECONDS). Receives the rule array as the second argument.

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

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