Hooks Reference

LicenceForge exposes WordPress actions and filters on both the server (your LicenceForge installation) and the client (the distributed plugin or theme). Use these hooks to extend, customise, or integrate with external systems without modifying core files.

Quick reference

Server-side actions

These actions fire on your LicenceForge server when licences are created through payment integrations.

wplf_license_created_from_stripe

Fires immediately after a new licence is created as a result of a completed Stripe Checkout session. Use this hook to send custom notifications, sync licence data to external CRMs, or trigger third-party workflows.

Parameters

Example

add_action( 'wplf_license_created_from_stripe', 'my_sync_to_crm', 10, 2 );

function my_sync_to_crm( array $result, array $session ) {
    // Send the new licence data to an external CRM via HTTP
    wp_remote_post( 'https://crm.example.com/api/licences', array(
        'body' => wp_json_encode( array(
            'email'        => $result['customer_email'],
            'name'         => $result['customer_name'],
            'product'      => $result['product_slug'],
            'license_id'   => $result['license_id'],
            'stripe_session' => $session['id'],
        ) ),
        'headers' => array(
            'Content-Type'  => 'application/json',
            'Authorization' => 'Bearer ' . CRM_API_KEY,
        ),
    ) );
}

wplf_license_created_from_woocommerce

Fires immediately after a new licence is created as a result of a completed WooCommerce order. This is the WooCommerce equivalent of the Stripe hook above.

Parameters

Example

add_action( 'wplf_license_created_from_woocommerce', 'my_log_wc_licence', 10, 2 );

function my_log_wc_licence( array $license_data, WC_Order $order ) {
    // Add an order note with the licence key for admin reference
    $order->add_order_note( sprintf(
        'LicenceForge: Licence %s created for product "%s" (limit: %d).',
        substr( $license_data['license_key'], 0, 9 ) . '...',
        $license_data['product_slug'],
        $license_data['activation_limit']
    ) );

    // Store the licence ID as order meta for later retrieval
    $order->update_meta_data( '_wplf_license_id', $license_data['license_id'] );
    $order->save();
}

Client-side filters

These filters fire on end-user sites where your plugin or theme (with the bundled LicenceForge client library) is active. They allow end users or integrators to customise client behaviour without modifying the client library files.

wplf_client_api_args

Filters the arguments passed to wp_remote_request() before every API call to the LicenceForge server. Use this to add custom headers, adjust timeouts, or configure proxy settings.

Parameters

Example

add_filter( 'wplf_client_api_args', 'my_custom_api_args' );

function my_custom_api_args( $args ) {
    // Increase timeout for slow connections
    $args['timeout'] = 30;

    // Add a custom header for server-side logging
    $args['headers']['X-Client-Version'] = '1.5.0';

    return $args;
}

wplf_client_is_valid

Filters the boolean result of a licence validation check. Runs after the API response is received and parsed. Use this to implement custom validation logic, such as domain whitelisting or development environment bypasses.

Parameters

Example

add_filter( 'wplf_client_is_valid', 'my_dev_bypass', 10, 2 );

function my_dev_bypass( $is_valid, $response ) {
    // Always treat local development sites as valid
    $host = wp_parse_url( home_url(), PHP_URL_HOST );
    if ( in_array( $host, array( 'localhost', '127.0.0.1' ), true ) ) {
        return true;
    }

    // Allow .test and .local TLDs for development
    if ( preg_match( '/\.(test|local)$/', $host ) ) {
        return true;
    }

    return $is_valid;
}

wplf_client_cache_duration

Filters the number of seconds that a validation result is cached in a WordPress transient before the client re-checks with the server. The default is 3600 seconds (1 hour).

Parameters

Example

add_filter( 'wplf_client_cache_duration', 'my_custom_cache_ttl' );

function my_custom_cache_ttl( $duration ) {
    // Cache for 12 hours instead of the default 1 hour
    return 43200;
}

wplf_client_has_feature

Filters the result of a feature check performed via WPLF_Client::has_feature(). Use this to grant or revoke access to specific features based on custom logic.

Parameters

Example

add_filter( 'wplf_client_has_feature', 'my_beta_feature_gate', 10, 2 );

function my_beta_feature_gate( $has_feature, $feature_slug ) {
    // Grant beta features to users who have opted in via a constant
    if ( 'beta-features' === $feature_slug && defined( 'MY_PLUGIN_BETA' ) && MY_PLUGIN_BETA ) {
        return true;
    }

    return $has_feature;
}

wplf_trust_proxy_headers

Filters whether the client library should trust the X-Forwarded-For header when detecting the site's IP address. Defaults to false. Enable this only if your site is behind a trusted reverse proxy or load balancer.

Parameters

Example

add_filter( 'wplf_trust_proxy_headers', '__return_true' );

Client-side actions

These actions fire on end-user sites during key licence lifecycle events.

wplf_client_activated

Fires immediately after a licence is successfully activated on the current site. Use this to trigger post-activation setup, display welcome messages, or log the event.

Parameters

Example

add_action( 'wplf_client_activated', 'my_post_activation_setup' );

function my_post_activation_setup( $response ) {
    // Set a flag so the plugin shows a welcome banner on next page load
    update_option( 'my_plugin_show_welcome', true );

    // Log activation for internal analytics
    error_log( sprintf(
        'My Plugin activated: site %s, activation %d of %d.',
        $response['site_url'],
        $response['activation_count'],
        $response['activation_limit']
    ) );
}

wplf_client_deactivated

Fires immediately after a licence is deactivated on the current site. Use this to clean up plugin data, disable premium features, or notify the user.

Parameters

Example

add_action( 'wplf_client_deactivated', 'my_cleanup_on_deactivation' );

function my_cleanup_on_deactivation( $response ) {
    // Remove cached premium template data
    delete_transient( 'my_plugin_premium_templates' );

    // Revert to free-tier settings
    update_option( 'my_plugin_tier', 'free' );
}

wplf_client_license_invalid

Fires when a licence validation check returns a permanent error -- specifically HTTP 401, 403, or 404 responses. This indicates the licence has been revoked, deleted, or the key is fundamentally invalid, as opposed to a transient network error.

Parameters

Example

add_action( 'wplf_client_license_invalid', 'my_handle_invalid_licence' );

function my_handle_invalid_licence( $error ) {
    // Disable premium functionality immediately
    update_option( 'my_plugin_premium_active', false );

    // Store the error for display in admin notices
    update_option( 'my_plugin_license_error', array(
        'code'    => $error['code'],
        'message' => $error['message'],
        'time'    => current_time( 'mysql' ),
    ) );

    // Notify the site administrator
    wp_mail(
        get_option( 'admin_email' ),
        'My Plugin: Licence Invalid',
        sprintf( 'Your licence is no longer valid. Reason: %s', $error['message'] )
    );
}

wplf_client_update_available

Fires when the update checker detects that a newer version of your product is available. Use this to display custom update banners, log update availability, or trigger pre-update tasks.

Parameters

Example

add_action( 'wplf_client_update_available', 'my_notify_update' );

function my_notify_update( $update_data ) {
    // Store update info for a custom admin banner
    update_option( 'my_plugin_update_available', array(
        'version'      => $update_data['new_version'],
        'requires_php' => $update_data['requires_php'],
        'checked_at'   => current_time( 'mysql' ),
    ) );
}

Related pages

• Extending LicenceForge -- Full examples of customisation using hooks
• REST API Reference -- Complete endpoint documentation
• Database Schema -- Table structures for context on hook data
• Client Library -- Integration overview for the bundled PHP classes