We have a new documentation site for cPanel & WHM! You can find our new documentation site at docs.cpanel.net.

We will continue to maintain our API documentation on this server.

Skip to end of metadata
Go to start of metadata

Introduction

Standardized Hooks trigger applications when cPanel & WHM performs an action. Use this system to execute custom code (hook action code) to customize how cPanel & WHM functions in specific scenarios (hookable events). For example, you could use this system to make certain that a script runs each time that a user creates an account.

Note:

For a step-by-step tutorial to create and register a hook, read our Tutorial - Create a Standardized Hook documentation. 

Basic usage

Each standardized hook is comprised of a hookable event, a hook action, and hook registration.

To create a new standardized hook, perform the following steps:

  1. Select a hookable event. — Hookable events set the action that triggers a hook, and whether the hook triggers before or after the event.

  2. Write your custom hook action code.
  3. Register the hook. — Use the /usr/local/cpanel/bin/manage_hooks Command Line Interface (CLI) utility to connect (register) the hook action code with the event.
    • The system includes a hooks registry for each hookable event. This allows hooks from your application to coexist with another application's hooks that reference the same event.
    • cPanel & WHM provides the /usr/local/cpanel/bin/manage_hooks CLI utility to manage standardized hooks.

Standardized Hook System data

Warning:

Do not edit this data manually. Instead, manage Standardized Hooks with the /usr/local/cpanel/bin/manage_hooks utility.

Note:

When the system updates to cPanel & WHM version 84, the system will convert and no longer use the following files:

hooks.db
hooks.db.json
hooks.yaml
hooks.cache

cPanel & WHM version 84 and later

Standardized Hooks System data is in subdirectories within the /var/cpanel/hooks/data/ directory. This allows the system to isolate individual events for better performance.

  • Each subdirectory includes a .yaml file and a .cache file.
  • For example, the /var/cpanel/hooks/data/Passwd/ directory could contain the change_password.yaml file and the change_password.cache file.

cPanel & WHM version 82 and earlier

Standardized Hooks System data is in the /var/cpanel/ directory. This is the authoritative reference for all standardized hook data.

  • The /var/cpanel/hooks.yaml file contains the hook database.
  • The /var/cpanel/hooks.cache file contains a cached copy of the database. The cache file regenerates automatically whenever you query the Standardized Hooks System internally or through a management utility. 

Remember:

If you have questions or need help with your customization project, join the conversation on our cPanel Developers Forum, or reach out to us in Discord.

We encourage anyone who develops for cPanel products to read the cPanel Blog and join our Plugin Developers mailing list.