Development Guides Home >> Guide to Standardized Hooks

Guide to Standardized Hooks - Hookable Events

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.
• DiskQuota — The DiskQuota category's events occur during disk quota processing.
• modsec_vendor script — The modsec_vendor script category's events occur when you run a WHM script . These scripts reside in the /usr/local/cpanel/scripts/ directory.
• ModSecurity — The ModSecurity ™ category's events occur during WHM functions.
• Passwd — The Passwd category's events occur when a WHM user or a cPanel user changes a cPanel user's password.
• PkgAcct — The PkgAcct category's events occur during backup creation.
• RPM::Versions — The RPM::Versions category creates hookable events for RPMs.
• Scripts — The scripts category's events occur when email scripts run.
• 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.

Advanced users can define additional hookable events in their custom modules.

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.