Hooks

What is a Hook?

Action Hooks allow you to add your own code to WHMCS that runs when specific events or actions occur inside the system. WHMCS has over 100 different hook points that you can tie custom code into, and more are being added with each new release.

The possibilities with hooks are endless, 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 additional custom actions when an order is placed in WHMCS
Sending notifications when certain events occur

There is also an index of hooks available.

Creating a Hook

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

Custom hook functions are usually passed variables when they are called, with the variables depending on the action the hook point relates to. Some hook points will also accept a return from your custom hook function, and that allows you to influence what the system does next from your custom code.

We recommend naming hook functions always starting with "hook_", followed by the filename, and then the particular action or task that hook is performing. For example "hook_filename_action" - "hook_forumsetup_addclient". This helps to ensure that no 2 hook functions from 2 separate developers ever conflict due to naming issues.

Sample Code

The best way to see how hooks work is with an example, so here's an example using the Client Signup hook event that could be used to create an account on an external system such as a forum:

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...
});

The Add Hook Function

This is the key function for hooks, and is how you define to WHMCS at what point your custom hook function should be called.

The first part defines the hook point. This must be one of the hook points WHMCS has implemented (listed in the pages below)
The number defines the priority of the hook, so for example if you have more than 1 hook for the ClientAdd function, the order in which the hooks should run
The third argument tells WHMCS which function name to call from this hook point. Anonymous functions, also known as closures, are also supported as demonstrated in the example above.

A commented out example hook file is included in WHMCS which you can use as a template. You'll find that in the folder /includes/hooks/

Module Hooks

Modules support hooks being defined that relate to a module within the relevant module directory; /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, and 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 are cached. So if you add a hooks file to a module retrospectively, once the module is already active, then before the system will detect and start running that module, you must edit and resave either the addon module configuration, product configuration or domain registrar configuration for the respective module for it to be detected.

Hook Points

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

Documentation