You can find our user documentation at

Check out our new API beta site!

Skip to end of metadata
Go to start of metadata


Hookable events set the action that triggers a hook, and whether the hook triggers before or after the event. Within any cPanel & WHM event (for example, an API call or binary process), the code contains the following phases:

  1. Preparation — The preparation of variables and the environment.

  2. Execution — The execution of specific operations.
  3. Rendering — The rendering of the operation's results via HTTP content headers and body.

cPanel & WHM events run routines before (pre) or after (post) the execution phase. 


Most pre events can signal a failure that skips the execution phase of the event entirely. The rendering phase uses this signal as if the failure occurred natively, before execution.

Hookable events

The Standardized Hooks system uses the following categories for hookable events:

  • ConvertAddon — The ConvertAddon category's events occur during WHM functions.
  • Cpanel — The Cpanel category creates hookable events for cPanel API 1, cPanel API 2, or UAPI functions.
  • PkgAcct — The PkgAcct category's events occur during backup creation.
  • Passwd — The Passwd category's events occur when a WHM user or a cPanel user changes a cPanel user's password.
  • RPM::Versions — The RPM::Versions category creates hookable events for RPMs.
  • Stats — The Stats category's events occur during statistics processing.
  • System — The System category's events occur during system updates or backups.
  • Whostmgr — The Whostmgr category's events occur during WHM functions.

Hookable event attributes

All hookable events are comprised of three main attributes:

  1. category — The event's logical grouping within cPanel & WHM.
  2. event — The event that cPanel & WHM performs.
  3. stage — The location of the trigger that runs the hook action code, relative to the event.

Some hookable events may include additional attributes:

  • blocking — Whether a returned failure from the hook action code prevents the event's execution. Only specific  pre -stage events can block.
  • escalateprivs — Whether the hookable event can escalate privileges before the hook action code runs. (Scripts only.)
  • Action Code Run As — The system user that owns the process that executes the hook action code.


These additional attributes are implicit implementation details that relate to the cPanel & WHM code that dispatches the hookable event.

If the blocking and escalateprivs attributes are present for a given event, the hook action code can use the describe method to define the rollback and escalateprivs attributes for registration.