Hooks

What is a Hook?

Action Hooks allow you to add your own code to WHMCS. The code will run when specific events or actions occur inside the system. WHMCS has over 100 different hook points. These you can tie custom code into. With each new release, WHMCS adds more hook points.

The possibilities with hooks are many, but some common examples of what you might use them for are:

Registering users in another system when they signup via WHMCS.
Keeping user details in sync with third party applications.
Performing extra custom actions when placing an order in WHMCS.
Sending notifications when certain events occur.

Creating a Hook

Hooks work by defining a function, and then tying that function into a hook point. Most custom hook functions are standalone hooks, and thus live in the /includes/hooks/ folder. Hooks can also be part of modules (more details later on this).

Custom hook functions have variables passed when called. The variables depend on the action the hook point relates to. Some hook points will also accept a return from the custom hook function. Returns will allow influence with what the system does next from the custom code.

WHMCS recommends naming hook functions always starting with "hook_". Following this, the filename. Finally the particular action or task that hook is performing. For example "hook_filename_action" - "hook_forumsetup_addclient". This will ensure that no hook functions ever conflict due to naming issues.

Sample Code

The best way to see how hooks work is with an example. Below is an example using the Client Signup hook event. A developer could use this event to create an account on an external system such as a forum:

/**
 * Add hook function call.
 *
 * @param string $hookPoint The hook point to call
 * @param integer $priority The priority for the given hook function
 * @param string|function Function name to call or anonymous function.
 *
 * @return Depends on hook function point.
 */
add_hook('ClientAdd', 1, function ($vars) 
{
    $userid = $vars['userid'];
    $firstname = $vars['firstname'];
    $lastname = $vars['lastname'];
    $email = $vars['email'];
    $password = $vars['password'];

    // Run code to create remote forum account here...
});

Anonymous functions, also known as closures, are supported for the function to be called as demonstrated in the example above.

Module Hooks

Modules support hooks that relate to a module within the relevant module directory. This is /modules/addons/ for addon, /modules/servers/ for provisioning and /modules/registrars/ for registrar modules.

To define hooks as part of a module, simple create a file named "hooks.php" within the module folder. A developer can then include all module specific hook related code within that file.

Note to Developers: Hook files in module folders are only called for active modules. And active modules that contain hooks become cached. If a developer add a hooks file to a module after activation, the cache must refresh. To refresh the cache, edit and re-save either the appropriate module configuration.

Hook Points

We've divided the hooks up into categories to help make the list more manageable. So choose an option from below to see the hooks which exist for that category.

Documentation