Hooks and Filters Reference
9 min read
- View as Markdown Open this page as plain Markdown (opens in a new tab)
- Open in ChatGPT Ask questions about this page (opens in a new tab)
- Open in Claude Ask questions about this page (opens in a new tab)
- Open in Google AI Studio Ask questions about this page (Google account required) (opens in a new tab)
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.
Updated on October 18, 2026