Integrating Content Access Events with External Systems via WordPress Hooks

Introduction

For WordPress developers and implementers, simply gating content often isn't enough. The true power lies in connecting those content access events to your broader business ecosystem. Imagine a visitor requests access to a whitepaper, gets approved, and then downloads it. Wouldn't it be valuable to log these interactions in your CRM, trigger a marketing automation sequence, or update a user profile in an external database?

This is where WordPress hooks become invaluable. The Gatekeeper Pro plugin provides a robust set of action and filter hooks that expose its core lifecycle events. These hooks allow you to intercept, modify, and extend the plugin's behaviour, enabling seamless integration with virtually any external system or custom workflow you can imagine.

Why Integrate Gated Content Events?

Integrating content access events with external systems opens up a world of possibilities for optimising your content strategy and improving user engagement. By connecting Gatekeeper Pro's workflow to your other platforms, you can achieve a more cohesive and automated operational flow.

• Enhanced Lead Nurturing: Automatically add new access requests to your CRM or email marketing platform, segmenting leads based on the content they've requested.

• Improved Analytics: Send detailed access and download events to your analytics platform, gaining deeper insights into content performance and user behaviour beyond basic WordPress metrics.

• Custom Workflows: Trigger specific actions in external tools, such as creating a support ticket when a high-value resource is accessed, or updating a user's status in a custom membership system.

• Data Synchronisation: Keep external user databases synchronised with content access permissions, ensuring consistent data across your entire digital landscape.

• Personalised User Experiences: Use access event data to dynamically tailor content recommendations or follow-up communications.

Understanding WordPress Hooks for Gated Content

WordPress hooks are the foundation of extensibility in the platform, allowing developers to "hook into" the execution process without modifying core files. Gatekeeper Pro leverages these hooks extensively, providing specific points where you can inject your custom code.

Action Hooks

Action hooks fire at specific moments in the Gatekeeper Pro workflow, allowing you to perform tasks without returning any data. They're perfect for sending notifications, logging events, or making API calls to external systems. When an action hook fires, it often passes relevant data as arguments to your custom function, such as the request ID, post ID, or user details.

For a comprehensive overview of available action hooks, refer to our article "Action Hooks for WordPress Content Gating: A Complete Reference".

Filter Hooks

Filter hooks, on the other hand, allow you to modify data before it's used or displayed by Gatekeeper Pro. You can change the content of an email, alter token expiry times, or adjust the fields displayed in the access request form. Your custom function receives data, modifies it, and then returns the modified data.

To learn more about customising content output, explore "Filter Hooks for Customising Gated Content Output on WordPress", and for modifying token behaviour, see "How to Modify Token Behaviour With WordPress Filters for Gated Content".

Key Gatekeeper Pro Action Hooks for Integration

Gatekeeper Pro offers several action hooks that are particularly useful for integrating with external systems. Here are some of the most common and their applications:

gatekeeper_pro_request_created

This action hook fires immediately after a new access request is created in the database. It's the ideal point to capture initial lead data and push it to external systems.

• When it fires: After a new access request is inserted, but before it's approved or disapproved.

• Data provided: $request_id (integer), $data (array — the full request data including post_id, user_name, user_email, user_company, user_phone, user_location, message, post_type, source_url).

• Use case: Send the initial request details to a CRM as a new lead, mark it as "pending review".

<?php
/**
 * Hook into Gatekeeper Pro's request created event.
 * Sends request data to an external CRM.
 *
 * @param int   $request_id The ID of the access request.
 * @param array $data       Full request data array.
 */
function my_custom_send_request_to_crm_on_submit( $request_id, $data ) {
    // Replace with your actual CRM API endpoint
    $crm_webhook_url = 'https://your-crm.com/api/leads';

    $post_title = get_the_title( $data['post_id'] );

    $payload = array(
        'first_name' => $data['user_name'] ?? '',
        'email'      => $data['user_email'] ?? '',
        'company'    => $data['user_company'] ?? '',
        'source'     => 'Gatekeeper Pro - ' . $post_title,
        'status'     => 'Pending Access',
        'request_id' => $request_id,
    );

    $response = wp_remote_post( $crm_webhook_url, array(
        'method'      => 'POST',
        'headers'     => array( 'Content-Type' => 'application/json' ),
        'body'        => json_encode( $payload ),
        'timeout'     => 10, // seconds
        'blocking'    => false, // Don't wait for the CRM response
        'sslverify'   => true,
    ) );

    if ( is_wp_error( $response ) ) {
        error_log( 'Gatekeeper Pro CRM integration error on submit: ' . $response->get_error_message() );
    }
}
add_action( 'gatekeeper_pro_request_created', 'my_custom_send_request_to_crm_on_submit', 10, 2 );
?>

gatekeeper_pro_request_approved

This action hook fires after an access request is approved and a token has been generated. This is often the most critical integration point, as it signifies a qualified lead gaining access.

• When it fires: After an admin approves an access request (via the dashboard or an email action link).

• Data provided: $request_id (integer), $request (array — the full request row including user_name, user_email, user_company, post_id, etc.), $token (array — with keys id, token, expires_at, ttl_hours).

• Use case: Update the lead status in CRM to "Approved Access", trigger an email drip campaign, or grant access to an external resource.

<?php
/**
 * Hook into Gatekeeper Pro's request approved event.
 * Updates CRM lead status and triggers a marketing automation sequence.
 *
 * @param int   $request_id The ID of the access request.
 * @param array $request    Full request data row.
 * @param array $token      Token data (id, token, expires_at, ttl_hours).
 */
function my_custom_crm_update_on_approved( $request_id, $request, $token ) {
    // Replace with your actual CRM API endpoint for updating leads
    $crm_api_endpoint = 'https://your-crm.com/api/lead/update';
    // Replace with your marketing automation system's API endpoint
    $ma_api_endpoint  = 'https://your-ma-system.com/api/trigger_sequence';

    $post_title = get_the_title( $request['post_id'] );

    // 1. Update CRM lead status
    $crm_data = array(
        'email'            => $request['user_email'],
        'status'           => 'Access Granted',
        'content_accessed' => $post_title,
        'token_expires'    => $token['expires_at'],
        'request_id'       => $request_id,
    );
    wp_remote_post( $crm_api_endpoint, array(
        'method'      => 'POST',
        'headers'     => array( 'Content-Type' => 'application/json' ),
        'body'        => json_encode( $crm_data ),
        'timeout'     => 10,
        'blocking'    => false,
        'sslverify'   => true,
    ) );

    // 2. Trigger marketing automation sequence
    $ma_data = array(
        'email'        => $request['user_email'],
        'sequence_id'  => 'gated_content_follow_up', // Specific sequence ID in your MA system
        'content_name' => $post_title,
    );
    wp_remote_post( $ma_api_endpoint, array(
        'method'      => 'POST',
        'headers'     => array( 'Content-Type' => 'application/json' ),
        'body'        => json_encode( $ma_data ),
        'timeout'     => 10,
        'blocking'    => false,
        'sslverify'   => true,
    ) );
}
add_action( 'gatekeeper_pro_request_approved', 'my_custom_crm_update_on_approved', 10, 3 );
?>

gatekeeper_pro_request_disapproved

This action hook fires after an access request is disapproved. Useful for logging or updating lead statuses for rejected requests.

• When it fires: After an admin disapproves an access request (via the dashboard or an email action link).

• Data provided: $request_id (integer), $request (array — the full request row).

• Use case: Mark the lead as "Access Denied" in CRM, or trigger an internal notification.

gatekeeper_pro_token_validated

This action hook fires every time a valid token is used to access gated content on the front end. It's invaluable for tracking actual content consumption, as it tells you exactly which post was accessed and which token was used.

• When it fires: After a user presents a valid token and the plugin unlocks content on a page.

• Data provided: $token (array — the full token row including id, user_email, token_type, access_count, last_accessed), $post_id (integer).

• Use case: Log content access events in an external analytics system or update a user's activity feed in a client portal.

<?php
/**
 * Hook into Gatekeeper Pro's token validated event.
 * Logs content access to an external analytics system.
 *
 * @param array $token   The full token row (id, user_email, token_type, access_count, etc.).
 * @param int   $post_id The ID of the post accessed.
 */
function my_custom_log_access_to_analytics( $token, $post_id ) {
    // Replace with your analytics API endpoint
    $analytics_api_url = 'https://your-analytics.com/api/track_event';

    $post_title = get_the_title( $post_id );

    $data = array(
        'event'        => 'gated_content_accessed',
        'email'        => $token['user_email'],
        'content_id'   => $post_id,
        'content_name' => $post_title,
        'token_id'     => $token['id'],
        'token_type'   => $token['token_type'],
        'access_count' => $token['access_count'],
        'timestamp'    => current_time( 'mysql' ),
    );

    wp_remote_post( $analytics_api_url, array(
        'method'      => 'POST',
        'headers'     => array( 'Content-Type' => 'application/json' ),
        'body'        => json_encode( $data ),
        'timeout'     => 10,
        'blocking'    => false,
        'sslverify'   => true,
    ) );
}
add_action( 'gatekeeper_pro_token_validated', 'my_custom_log_access_to_analytics', 10, 2 );
?>

gatekeeper_pro_file_streamed

This action hook fires immediately before a protected file is streamed to the user via the secure proxy endpoint. It's the definitive signal that a file download has occurred, making it ideal for download tracking and audit logging.

• When it fires: After token validation succeeds and just before the file bytes are sent to the browser.

• Data provided: $attachment_id (integer — the WordPress attachment ID of the file), $token (array — the full validated token row including user_email, id, token_type).

• Use case: Log file download events to an external analytics system, update a CRM record with "downloaded" status, or trigger a follow-up email sequence.

Step-by-Step Tutorial: Sending Approved Access Request Data to a CRM via Webhook

Let's walk through a practical example: automatically sending the details of an approved access request, including the content accessed and the user's details, to a hypothetical CRM system via a webhook. This assumes your CRM has an API endpoint that accepts POST requests with JSON payloads.

Step 1: Identify the Trigger Event

For an approved access request, the most appropriate hook is gatekeeper_pro_request_approved. This hook provides all the necessary information: the request ID, the full request data, and the generated token details.

Step 2: Understand the Hook Data

The gatekeeper_pro_request_approved hook passes three arguments to your custom function:

1. $request_id (integer): The unique ID of the access request.

2. $request (array): The full request row from the database, including post_id, user_name, user_email, user_company, user_phone, user_location, message, post_type, and source_url.

3. $token (array): The generated token data with keys id, token, expires_at, and ttl_hours.

You'll use these arguments to construct the data payload for your CRM.

Step 3: Define Your External System's API/Webhook

Before writing code, you need to know:

• Webhook URL: The exact endpoint your CRM listens to (e.g., https://your-crm.com/api/new-lead).

• Authentication: Does it require an API key in the headers or as a query parameter? (For simplicity, we'll assume no complex auth in this example, but it's crucial in real-world scenarios).

• Expected Payload: What JSON structure does your CRM expect? Common fields include email, first_name, last_name, company, source, and custom fields for gated content details.

Step 4: Implement the Integration Logic

You'll create a custom PHP function that hooks into gatekeeper_pro_request_approved. Inside this function, you'll prepare the data, encode it as JSON, and send it to your CRM using WordPress's built-in wp_remote_post() function.

<?php
/**
 * Integrates Gatekeeper Pro's approved access requests with an external CRM.
 * This function sends user data and content details to a CRM webhook.
 *
 * @param int   $request_id The ID of the access request.
 * @param array $request    Full request data row from the database.
 * @param array $token      Token data (id, token, expires_at, ttl_hours).
 */
function saucecode_integrate_approved_request_with_crm( $request_id, $request, $token ) {
    // --- Configuration ---
    // IMPORTANT: Replace with your actual CRM webhook URL and API Key (if required)
    $crm_webhook_url = 'https://api.yourcrm.com/v1/leads';
    $crm_api_key     = 'YOUR_CRM_API_KEY_HERE'; // Or in environment variables

    // --- Prepare Data Payload ---
    $post_title = get_the_title( $request['post_id'] );
    $post_url   = get_permalink( $request['post_id'] );

    // Extract relevant data from the $request array
    $full_name = $request['user_name'] ?? '';
    $email     = $request['user_email'] ?? '';
    $company   = $request['user_company'] ?? '';
    $phone     = $request['user_phone'] ?? '';

    // Split name into first and last if possible
    $name_parts     = explode( ' ', $full_name, 2 );
    $crm_first_name = $name_parts[0] ?? '';
    $crm_last_name  = $name_parts[1] ?? '';

    $crm_payload = array(
        'email'         => $email,
        'firstName'     => $crm_first_name,
        'lastName'      => $crm_last_name,
        'company'       => $company,
        'phone'         => $phone,
        'leadSource'    => 'Gatekeeper Pro Content Gating',
        'status'        => 'Content Access Approved',
        'gatedContent'  => array(
            'title'      => $post_title,
            'url'        => $post_url,
            'requestId'  => $request_id,
            'tokenId'    => $token['id'],
            'expiresAt'  => $token['expires_at'],
        ),
        'notes'         => 'Requested and approved access to: ' . $post_title,
    );

    // --- Send Data to CRM ---
    $headers = array(
        'Content-Type' => 'application/json',
        // Add API key to headers if your CRM requires it (e.g., 'Authorization' => 'Bearer ' . $crm_api_key)
    );

    $response = wp_remote_post( $crm_webhook_url, array(
        'method'      => 'POST',
        'headers'     => $headers,
        'body'        => json_encode( $crm_payload ),
        'timeout'     => 15,          // Max time in seconds to wait for the CRM response
        'blocking'    => false,       // Set to false to prevent blocking WordPress execution
        'sslverify'   => true,        // Always verify SSL certificates
        'data_format' => 'body',
    ) );

    // --- Error Handling (for logging, as 'blocking' is false) ---
    if ( is_wp_error( $response ) ) {
        error_log( 'Gatekeeper Pro CRM integration failed for request ID ' . $request_id . ': ' . $response->get_error_message() );
    } else {
        $response_code = wp_remote_retrieve_response_code( $response );
        if ( $response_code < 200 || $response_code >= 300 ) {
            error_log( 'Gatekeeper Pro CRM integration received non-2xx response for request ID ' . $request_id . ': ' . $response_code );
            error_log( 'CRM Response Body: ' . wp_remote_retrieve_body( $response ) );
        } else {
            // Optionally log success
            // error_log( 'Gatekeeper Pro CRM integration successful for request ID ' . $request_id );
        }
    }
}
add_action( 'gatekeeper_pro_request_approved', 'saucecode_integrate_approved_request_with_crm', 10, 3 );
?>

Step 5: Place Your Code

You should place this code in one of the following locations:

• A custom plugin: This is the recommended approach for any custom functionality. It ensures your code is active regardless of the theme and can be easily managed.

• Your child theme's functions.php file: If you're confident this functionality is tightly coupled to your theme, but be aware it will be lost if you change themes (unless using a child theme).

Avoid placing custom code directly in a parent theme's functions.php, as it will be overwritten during theme updates.

Advanced Integration Scenarios

Beyond basic CRM updates, Gatekeeper Pro's hooks enable more complex and powerful integrations:

• Triggering Email Sequences: Use the gatekeeper_pro_request_approved hook to subscribe a user to a specific email sequence in an email service provider (ESP) like Mailchimp or Campaign Monitor.

• Updating User Roles in External Systems: For a client portal, you might use gatekeeper_pro_request_approved to update a user's role or status in an external identity management system or even a custom WordPress user meta field if they are logged in.

• Real-time Analytics Dashboards: Send token access events to a data warehouse or business intelligence tool, enabling real-time monitoring of content engagement.

• Custom Notifications: Fire a Slack notification to your team whenever a specific high-value content piece is requested or approved.

• Conditional Logic: Combine action hooks with conditional logic to perform different integrations based on the content type, user's email domain, or other form data. For example, send B2B requests to one CRM and B2C to another.

Best Practices for Integration

When integrating with external systems, keep these best practices in mind to ensure reliability and performance:

• Asynchronous Processing: Whenever possible, use non-blocking requests ('blocking' => false in wp_remote_post()) or offload heavy tasks to background processes (e.g., using WP-Cron or a custom queue) to prevent slowing down your WordPress site.

• Error Handling and Logging: Implement robust error checking for API calls and log any failures. This helps diagnose issues if your external system integration stops working.

• Security: Never hardcode sensitive API keys directly in publicly accessible files. Use environment variables, WordPress constants, or secure options. Always use SSL/TLS for API communication ('sslverify' => true).

• Data Sanitisation: Although data from Gatekeeper Pro's hooks is generally safe, always sanitise any data you send to external systems, especially if it's user-generated.

• Testing: Thoroughly test your integrations in a staging environment before deploying to production. Ensure all possible scenarios (success, failure, different data types) are covered.

• Documentation: Document your custom integrations, including the hooks used, the purpose of the integration, and any external API details.

Conclusion

WordPress Gatekeeper Pro's extensive use of action and filter hooks empowers developers to move beyond basic content gating. By leveraging these hooks, you can seamlessly integrate content access events into your existing business systems, automating workflows, enriching data, and gaining deeper insights into your audience's engagement. This extensibility allows you to craft a truly bespoke and powerful content strategy that aligns perfectly with your operational needs.