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.

Child pages
  • Guide to Standardized Hooks - Function Hooks
Skip to end of metadata
Go to start of metadata



Function hook scripts run automatically, after a specific cPanel API function. You can associate each hook with a single cPanel API 1 or cPanel API 2 function. Because function hooks run after an API function, they cannot block or modify events on the server. 


This hook method is deprecated. To convert function hooks to use the Standardized Hooks system, use the API::Module::function Cpanel event in your Hook Action Code.

Basic usage

To create a function hook, perform the following steps:

  1. Write a function hook script.
  2. Store the function hook script in the /usr/local/cpanel/hooks/module/function/ directory, where module is the cPanel API 1 or cPanel API 2 module name, and function is the function name.
    • For example, store a script that runs after the Email::addpop function in the /usr/local/cpanel/hooks/Email/addpop/ directory.
  3. Run the  /usr/local/cpanel/bin/register_hooks script to register the function hook.
    • Run this script every time that you add a new hook script or modify an existing hook script.
    • This script cannot register scripts that have incorrect file permissions.


You can write function hook scripts in any programming language.


  • Function hook scripts run as the root user.
  • You must set script file permissions to 0700.
  • Function hook scripts cannot produce output. You must silence any header content that your script's interpreter generates.

The system sends two types of data to STDIN whenever it runs a function hook script:

  1. The input parameters from the associated function call, in <cpanelevent> tags.
  2. A hash of user data, in <CPDATA> tags. This data includes the contents of the user's file in the /var/cpanel/users/ directory.

Example XML data  

 Click to view...

The following XML data is an example of the input that a function hook script could receive from STDIN:

  <IP> </IP>

Example Perl script

 Click to view...


Do not run this type of script on a production server. Password logging is a severe security risk. 

The following Perl script uses the XML data from STDIN to create a log of new email accounts and passwords in the /root/email_password_log file.

use strict;
use warnings;
use XML::Simple;
use Data::Dumper;
my $xml;
while (<STDIN>) {
        $xml .= $_;
my $xml_hashed = XMLin($xml);
my $username = $xml_hashed->{'cpanelevent'}->{'params'}->{'email'} . '@' . $xml_hashed->{'cpanelevent'}->{'params'}->{'domain'};
my $password = $xml_hashed->{'cpanelevent'}->{'params'}->{'password'};
open(my $fh, ">>", "/root/email_password_log");
print {$fh} "Email Account Created:\n";
print {$fh} "\tusername: $username\n";
print {$fh} "\tpassword: $password\n\n";

Example PHP code

 Click to view...


Do not read input from STDIN through a CGI application. You must treat this input as a CLI application.

To do this, add the following shebang line to the top of your PHP script:

#!/usr/bin/php-cgi -q

The following PHP code retrieves input from STDIN :

$stdin_fh = fopen('php://stdin', 'r');
while ($line = fgets( $stdin_fh )) {
    $xml_string .= $line;