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:
Preparation — The preparation of variables and the environment.
- Execution — The execution of specific operations.
- 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.
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.
The Standardized Hooks system uses the following categories for hookable events:
ConvertAddoncategory's events occur during WHM functions.
Cpanelcategory creates hookable events for cPanel API 1, cPanel API 2, or UAPI functions.
PkgAcctcategory's events occur during backup creation.
Passwdcategory's events occur when a WHM user or a cPanel user changes a cPanel user's password.
RPM::Versionscategory creates hookable events for RPMs.
Statscategory's events occur during statistics processing.
Systemcategory's events occur during system updates or backups.
Whostmgrcategory's events occur during WHM functions.
Advanced users can define additional hookable events in their custom modules.
Hookable event attributes
All hookable events are comprised of three main attributes:
category— The event's logical grouping within cPanel & WHM.
event— The event that cPanel & WHM performs.
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.
escalateprivs attributes are present for a given event, the hook action code can use the
describe method to define the
escalateprivs attributes for registration.