WHMCS Hooks Complete Guide 2026: Step-by-Step Tutorial with Examples

WHMCS Hooks Complete Guide 2026: Everything You Need to Know

WHMCS hooks are powerful tools that allow you to extend and customize your WHMCS installation without modifying core files. In this comprehensive 2026 guide, we'll cover everything from basic concepts to advanced implementation patterns.

What Are WHMCS Hooks?

WHMCS hooks are event triggers that allow you to execute custom code at specific points in the WHMCS workflow. They enable you to:

Modify data before it's processed
Add custom functionality to existing processes
Integrate third-party services
Customize client area and admin interfaces
Automate business processes

Types of WHMCS Hooks

1. Pre-Hooks (Before Actions)

Pre-hooks execute before an action occurs, allowing you to modify data or prevent actions:

add_hook("PreInvoiceCreation", 1, function($vars) {
    // Modify invoice data before creation
    $vars["amount"] = $vars["amount"] * 1.1; // Add 10% fee
    return $vars;
});

2. Post-Hooks (After Actions)

Post-hooks execute after an action completes, perfect for logging or notifications:

add_hook("AfterModuleCreate", 1, function($vars) {
    // Send notification after service creation
    $serviceId = $vars["serviceid"];
    // Your notification code here
});

3. Output Hooks

Output hooks modify what users see in the client area:

add_hook("ClientAreaPage", 1, function($vars) {
    // Add custom content to client area pages
    return array("customContent" => "Your custom HTML");
});

Most Common WHMCS Hooks in 2026

Payment Processing Hooks

PreInvoiceCreation - Modify invoice before creation
InvoiceCreated - Actions after invoice creation
InvoicePaid - Trigger actions when payment received
InvoicePaymentReminder - Customize payment reminders

Service Management Hooks

AfterModuleCreate - After service creation
AfterModuleSuspend - After service suspension
AfterModuleUnsuspend - After service reactivation
AfterModuleTerminate - After service termination

Client Area Hooks

ClientAreaPage - Modify client area pages
ClientAreaProductDetails - Customize product details
ClientAreaHomepagePanels - Add dashboard widgets

Step-by-Step: Creating Your First Hook

Step 1: Create a hook file in /includes/hooks/

// File: /includes/hooks/custom_hooks.php
<?php
use WHMCS\Database\Capsule;

// Your hook code here
?>

Step 2: Register your hook

add_hook("InvoicePaid", 1, function($vars) {
    $invoiceId = $vars["invoiceid"];
    
    // Your custom logic
    logActivity("Invoice #" . $invoiceId . " paid via hook");
    
    // Example: Activate service automatically
    $command = "ActivateModule";
    $postData = array(
        "serviceid" => $vars["serviceid"]
    );
    localAPI($command, $postData);
});

Step 3: Test your hook

Always test hooks in a development environment first. Use WHMCS logs to debug:

logActivity("Hook executed: " . print_r($vars, true));

Best Practices for WHMCS Hooks in 2026

1. Performance Optimization

Keep hook code lightweight and efficient
Use database queries sparingly
Cache frequently accessed data
Avoid nested loops in hooks

2. Error Handling

add_hook("InvoicePaid", 1, function($vars) {
    try {
        // Your code here
    } catch (Exception $e) {
        logActivity("Hook Error: " . $e->getMessage());
        // Don't break the main process
    }
});

3. Security Considerations

Always validate and sanitize input data
Use prepared statements for database queries
Check user permissions before actions
Never expose sensitive data in logs

Real-World Examples

Example 1: Auto-Activate Service on Payment

add_hook("InvoicePaid", 1, function($vars) {
    $invoiceId = $vars["invoiceid"];
    
    // Get invoice items
    $invoice = localAPI("GetInvoice", array("invoiceid" => $invoiceId));
    
    foreach ($invoice["items"]["item"] as $item) {
        if ($item["type"] == "Hosting") {
            // Activate the service
            localAPI("ModuleCreate", array(
                "accountid" => $item["relid"]
            ));
        }
    }
});

Example 2: Custom Email Notification

add_hook("AfterModuleCreate", 1, function($vars) {
    $serviceId = $vars["serviceid"];
    $userId = $vars["userid"];
    
    // Get client email
    $client = localAPI("GetClientsDetails", array("clientid" => $userId));
    
    // Send custom email
    sendMessage("Service Created Template", $userId, array(
        "service_id" => $serviceId
    ));
});

Example 3: Add Custom Field to Client Area

add_hook("ClientAreaProductDetails", 1, function($vars) {
    $serviceId = $vars["serviceid"];
    
    // Get custom data
    $customData = Capsule::table("tblhosting")
        ->where("id", $serviceId)
        ->value("customdata");
    
    return array("customField" => $customData);
});

Common Hook Mistakes to Avoid

Infinite Loops: Don't trigger hooks that call the same hook
Missing Return Values: Some hooks require return values
Not Checking Conditions: Always validate before executing
Poor Error Handling: Always wrap in try-catch blocks
Hardcoding Values: Use configuration instead

Testing and Debugging Hooks

Enable Hook Logging

Add this to your hook for debugging:

add_hook("InvoicePaid", 1, function($vars) {
    logModuleCall("custom_hook", "InvoicePaid", $vars, "", "", array());
    // Your code
});

Use WHMCS Logs

Check Utilities > Logs > Module Log for hook execution logs.

WHMCS 8.x Hook Updates

WHMCS 8.x introduced several new hooks and improvements:

Better hook performance
New API-related hooks
Enhanced security features
Improved error handling

Conclusion

WHMCS hooks are essential for customizing and extending your billing system. By following this guide and best practices, you can create powerful customizations that enhance your WHMCS installation without modifying core files.

For more advanced WHMCS customization needs, check out our premium WHMCS modules that include pre-built hooks and automation features.