Our Standardized Hooks system implements several methods of hooking into cPanel & WHM functionality. For the first time, these hooking systems are unified into a single, standard system.

The Standardized Hooks system is useful for developers and administrators who want to automatically trigger a script or application when a specific action is performed in cPanel. It allows you to customize the way cPanel functions and communicates with external systems across a variety of different scenarios.

Some important features of the Standardized Hooks system are:

You can run multiple hooks when a single action occurs.
The system allows you to write a hook as a Perl module or any other script.
The Standardized Hooks systems is consistent with the management interface (CLI).
This system provides a framework to determine how a hook should execute and what the hook should do in case of a failure.
The Standardized Hooks system can hook into most major accounting features, API 1, API 2, and some system functionality.
This system can deny certain actions.
The Standardized Hooks system allows your applications to co-exist with other applications on a cPanel & WHM server, without having overlap issues when both applications hook into the same function.

General concepts

The Standardized Hooks system functions from a hooks database that contains all of the hooks that exist on a system.

This database (sometimes called a registry) contains basic information about the system's hooks. This information includes whether the hook is a module or script, the order in which the hook(s) will run, and the user as which the hook will run. These parameters are all controlled by the /var/cpanel/hooks.yaml YAML file.

Hooks database

This file contains entries (or multiple entries) for each hook on the system. These entries contain the various attributes that describe how the hook is run.

This file is located at /var/cpanel/hooks.yaml

Each of the following parameters is required:

Parameter	Description
namespace	The hook insertion point's namespace.
function	The hook insertion point's function within the specified namespace.
stage	The stage of the function at which to execute the hook.
hook	The path to the application or script (hook) to run.

The following parameters are optional:

Parameter	Description
escalateprivs	A boolean value that indicates whether the hook should run as `root`.
check	A string value that points to another piece of code, which determines whether the hook will run.
rollback	A string value that points to another piece of code, which executes whenever a hook fails. For more information, view our Advanced Hook Usage documentation.
weight	The priority for running the hook. Lower numbers indicate the hook should execute earlier. This value defaults to `1000`, and can be set to any integer `0` or greater.

Remember: This file does not exist on cPanel & WHM systems until a standardized hook is created.

Contexts (hook insertion points)

cPanel & WHM contains code that defines hook insertion points. These hook insertion points are also called contexts, and are ultimately responsible for calling the Standardized Hooks system.

A hook insertion point is defined with a few parameters.

The following parameters are required:

Parameter	Description
namespace	The namespace of the function to call. This value determines which hash should be pulled from `/var/cpanel/hooks.yaml`. Some examples include `PkgAcct`, `Whostmgr`, and `Stats`.
function	The function on which the hook will act (e.g., `Accounts::Create` or `RestorePkg`).
stage	The stage of the hook. This value is generally `pre` or `post`, indicating whether the hook should be called before or after the specified action.

Note: All of the required arguments are used within the hooks database. This is because the system uses the parameters defined here, in the context, to determine whether the hook should run.

The following parameters are optional:

Parameter	Description
escalateprivs	A boolean value that indicates whether or not the call should be allowed to run with `root` privileges.
blocking	A boolean value specifying how the overlying code will behave if the hook fails. This parameter has important implications when dealing with hooks that can roll back (undo) their actions.

Execution types

When using this system, your hook can be either a Perl module or a script. There are advantages and disadvantages to each method. The following section attempts to compare those advantages and disadvantages.

Generally, it is best to write a Perl module hook unless you have a specific reason to do otherwise. For example, if you have no knowledge or Perl, require escalated privileges, or if a critical Perl module is not compatible with cPanel's internal Perl, you should use a script hook.

Scripts

Scripts are slower than modules.
Scripts do not provide as much access to cPanel & WHM internals as Perl modules.
Scripts allow you development in multiple languages.
Scripts can run with escalated privileges.

Perl modules

Perl modules are faster than scripts because they do not require executing another process.
Perl modules provide full access to processes that execute the application.
Perl modules use fewer resources because the system does not need to execute another binary in order to run the module.

Software Development Kit

Standardized Hooks: Abstract

Introduction