Action Hooks

Havenlytics action hooks are the do_action() events the plugin fires at key moments during its lifecycle, rendering, and data operations. They let you run your own code — logging, CRM sync, custom markup, integrations — without editing a single plugin file. This reference documents every action hook that exists in Havenlytics 3.3.1, grouped by subsystem, with the exact parameters each one passes.

Note: Every Havenlytics hook is prefixed hvnly_. There are no havenlytics_ hooks. If a hook name is not listed on this page, it does not exist in the plugin — do not rely on it.

How action hooks work in Havenlytics

Havenlytics fires actions with the standard WordPress do_action() function. You subscribe with add_action(), matching the hook name and the number of arguments it passes:

<?php
/**
 * Run custom setup after Havenlytics has fully loaded.
 * Fired once, at the end of the plugin boot sequence.
 */
add_action( 'hvnly_loaded', function () {
    // All Havenlytics services, CPTs and REST routes are now available.
    if ( function_exists( 'HVNLY_NAB' ) ) {
        // e.g. warm a cache, register an integration, etc.
    }
} );

When a hook passes parameters, declare the priority and the argument count in add_action() so WordPress hands them to your callback:

<?php
// hvnly_property_agents_saved passes ( int $property_id, array $agent_ids )
add_action( 'hvnly_property_agents_saved', function ( $property_id, $agent_ids ) {
    error_log( sprintf(
        'Property %d now has %d assigned agent(s).',
        $property_id,
        count( $agent_ids )
    ) );
}, 10, 2 ); // priority 10, accepts 2 arguments

Lifecycle & bootstrap actions

These fire as the plugin and its modules initialize. Use them to register integrations at the right moment.

Settings & cache actions

Fire after configuration changes or cache clears — ideal for invalidating your own caches in sync with Havenlytics.

Template & layout actions

These are the injection points inside Havenlytics templates. Hook them to add markup around content regions, single-property sections, or the property loop.

Tip: hvnly_get_template_part_{$slug} is a dynamic hook. The {$slug} is replaced by the template-part slug being loaded, so hvnly_get_template_part('content','single-property') fires hvnly_get_template_part_content.

Archive, card & shortcode actions

Agent & agency actions

Agent Workspace & portal actions

Authentication, identity & provisioning actions

Email verification actions

Email pipeline actions

Contact Agent (inquiry) actions

Worked examples

1. Inject a banner above every property archive card

<?php
add_action( 'hvnly_before_archive_property', function () {
    echo '<div class="my-featured-ribbon">New this week</div>';
} );

2. Push new inquiries into an external CRM

<?php
add_action( 'hvnly_contact_agent_inquiry_created', function ( $inquiry_id, $row ) {
    // $row contains sender_name, sender_email, property_id, message, etc.
    wp_remote_post( 'https://crm.example.com/api/leads', array(
        'timeout' => 5,
        'headers' => array( 'Content-Type' => 'application/json' ),
        'body'    => wp_json_encode( array(
            'name'     => $row['sender_name']  ?? '',
            'email'    => $row['sender_email'] ?? '',
            'property' => $row['property_id']  ?? 0,
            'source'   => 'havenlytics',
        ) ),
    ) );
}, 10, 2 );

3. Notify a Slack channel when an agent is approved

<?php
add_action( 'hvnly_workspace_registration_status_changed', function ( $user_id, $status, $agent_id, $previous ) {
    if ( 'approved' !== $status ) {
        return;
    }
    $user = get_userdata( $user_id );
    wp_remote_post( 'https://hooks.slack.com/services/XXX/YYY/ZZZ', array(
        'body' => wp_json_encode( array(
            'text' => sprintf( 'Agent approved: %s', $user ? $user->user_email : $user_id ),
        ) ),
    ) );
}, 10, 4 );

Best practices

• Match the argument count. If a hook passes two parameters, register with add_action( $hook, $cb, 10, 2 ). Omitting the count means your callback silently receives fewer arguments.
• Register on hvnly_loaded or later when your integration depends on Havenlytics services (HVNLY_NAB(), CPTs, REST routes).
• Keep template-hook callbacks output-only. Hooks like hvnly_before_main_content run mid-render — echo markup, don’t perform heavy queries there.
• Prefer filters for data changes. Actions are for side effects; to change property data, queries, or template paths, use the corresponding Havenlytics filter hooks instead.

Performance recommendations

Performance: Actions that fire inside loops — hvnly_before_archive_property, hvnly_property_loop_start, hvnly_get_template_part_{$slug} — run once per item. Avoid database calls or remote requests inside them; precompute data on hvnly_loaded or cache it.

• Offload slow work (CRM sync, webhooks) from request-time hooks by scheduling it with wp_schedule_single_event() and processing it via WP-Cron.
• Use the cache actions (hvnly_cache_cleared, hvnly_property_query_cache_invalidated) to invalidate your own caches in lockstep, rather than clearing them on every request.

Security notes

Security: Hook payloads are data, not trusted output. Escape everything you print inside template actions with esc_html(), esc_attr(), or esc_url(), and treat inquiry fields (hvnly_contact_agent_inquiry_created) as untrusted user input before sending them anywhere.

• Never expose user email, tokens, or identity data from hvnly_workspace_* and hvnly_email_verification_* hooks to the front end or logs in production.
• When calling external services from an action, use wp_remote_post() with a short timeout and validate/sanitize the payload first — a hook firing is not authorization to leak PII.

Common mistakes

• Forgetting the argument-count parameter in add_action(), so parameters arrive as null.
• Trying to modify data inside an action — actions do not use return values; use the matching filter hook instead.
• Assuming a hook fires on every request — many (e.g. hvnly_workspace_*) only fire in the Agent Workspace context, and admin-only actions never fire on the front end.