Difference between revisions of "Hooks"

Revision as of 15:58, 5 July 2011

Action hooks allow you to add your own code that will run when specific actions occur in WHMCS. For example, this can be used for things like performing other actions when an order is placed, sending an SMS message when a support ticket is opened, updating a users details in another application when a change is made in WHMCS, and many more...

How It Works

Hooks work by creating a file in the includes/hooks folder. Within the file, you need to declare a function that performs the action you want to run. That function will be passed variables from WHMCS, and the values you get depend on the hook being called. All hooks and the variables they will be passed are listed below. After defining your function, you then add the hook to WHMCS which is done by calling the add_hook function:

function create_forum_account($vars) {
    print_r($vars);
}
add_hook("ClientAdd",1,"create_forum_account");

The first part defines the hook point. This must be one of the values from below: ClientAdd, AddInvoicePayment, TicketOpen, etc...
The number defines the priority so if you have more than 1 hook for the ClientAdd function, the order in which the hooks should run
The third argument tells WHMCS which function to run at this hook point and so this is the name of the function which you have written in your hook file

Two example hook files are included which you'll find in the hooks folder - one basic example showing the file format and another providing a fully working example of a ClientAdd hook to validate an entered Tax/VAT ID Number.

Hook Points

Hooks are separated into categories to help you decide which hook point you should use.

@@ Line 18: / Line 18: @@
 ==Hook Points==
-Below is a full list of hook points you can tap into and the variables that are passed into each one in the $vars array:
+Hooks are separated into categories to help you decide which hook point you should use.
-===Clients===
+{{Hook_Categories}}
- ClientAdd - userid, firstname, lastname, companyname, email, address1, address2, city,
-              state, postcode, country, phonenumber, password
- ClientEdit - userid, firstname, lastname, etc... (containing new details), olddata (an array
-              of previous values)
- ClientLogin - userid
- ClientLogout - userid
- ClientChangePassword - userid, password
- ClientDetailsValidation - $_POST
- ClientClose - userid
- ClientDelete - userid
- PreDeleteClient - userid
-===Contacts===
- ContactAdd - userid, contactid, firstname, lastname, companyname, email, address1, address2,
-              city, state, postcode, country, phonenumber, subaccount, permissions,
-              domainemails, generalemails, invoiceemails, productemails, supportemails
- ContactEdit - same as above
-===Products/Services===
- AfterModuleCreate - params (an array of vars, same as module functions)
- AfterModuleSuspend - params
- AfterModuleUnsuspend - params
- AfterModuleTerminate - params
- AfterModuleChangePassword - params
- AfterModuleChangePackage - params
- AddonActivation - id, userid, serviceid, addonid
- PreDomainRegister - params, domain
- AfterRegistrarRegistration - params
- AfterRegistrarTransfer - params
- AfterRegistrarRenewal - params
- AdminServiceEdit - serviceid
- CancellationRequest - userid, relid, reason, type
- AfterProductUpgrade - upgradeid
- AfterConfigOptionsUpgrade - upgradeid
-===Order Process===
- ShoppingCartValidateProductUpdate - runs after updating cart, can use global $errormessage
-              to pass back error
- ShoppingCartValidateCheckout - runs when checkout is clicked, can use global $errormessage
-              to pass back error
- PreCalculateCartTotals - products, addons, domains, paymentmethod, etc...
- PreShoppingCartCheckout - as above
- AfterShoppingCartCheckout - OrderID, OrderNumber, InvoiceID, Products, Addons, Domains
- ShoppingCartCheckoutCompletePage - orderid, ordernumber, invoiceid, ispaid, amount,
-              paymentmethod
- AcceptOrder - orderid
- CancelOrder - orderid
- FraudOrder - orderid
- PendingOrder - orderid
- DeleteOrder - orderid
-===Invoicing===
-====InvoiceCreated====
-This hook is called when a new invoice has been generated by either the cron or order form but only after it has already been emailed to the client.
-'''Variables'''
-*invoiceid
-====InvoiceCreationPreEmail====
-This hook is called when a new invoice has been generated by either the cron or order form but before it is emailed so that the invoice can be edited prior to being sent
-'''Variables'''
-*invoiceid
-====InvoiceCreationAdminArea====
-This hook point runs when an invoice is manually created via the admin area so at this stage it will contain no line items or amount
-'''Variables'''
-*invoiceid
-====UpdateInvoiceTotal====
-This hook is called every time an invoice is edited, this applies to changes made by admin users within the admin area and when an invoice is generated by the cron or order process
-'''Variables'''
-*invoiceid
-====AddInvoicePayment====
-This hook is called every time a payment is applied to an invoice. It will not necessarily be for the total balance, and could just be a partial payment being applied to the invoice (unlike the InvoicePaid hook point)
-'''Variables'''
-*invoiceid
-====InvoicePaid====
-This hook point is called when an invoice changes from Unpaid to Paid status ie. when it becomes paid in full
-'''Variables'''
-*invoiceid
-====InvoiceUnpaid====
-This hook point is called when an invoice is set back to unpaid by an admin user
-'''Variables'''
-*invoiceid
-====InvoiceCancelled====
-This hook point is called when an invoice is marked as cancelled by an admin user
-'''Variables'''
-*invoiceid
-====InvoiceRefunded====
-This hook is called when an invoice is refunded in full, either to a clients credit balance or back to the gateway the payment was originally made from
-'''Variables'''
-*invoiceid
-====ManualRefund====
-This hook point is called whenever a refund is applied to an invoice using the "Record Only" option so no credit or remote gateway refund action is performed
-'''Variables'''
-*transid
-*amount
-====AddTransaction====
-This hook point is called every time a transaction is added to the system. It will not necessarily be a transaction being added to an invoice, it could be a credit transaction, a refund, or an expenditure entry by staff
-'''Variables'''
-*id
-*userid
-*currency
-*gateway
-*date
-*description
-*amountin
-*fees
-*amountout
-*rate
-*transid
-*invoiceid
-*refundid
-====LogTransaction=====
-This hook point is called every time a gateway log entry is created in Billing > Gateway Log and can be used to perform your own custom tasks based on gateway returns.
-'''Variables'''
-*date
-*gateway
-*data
-*result
-====AddInvoiceLateFee====
-This hook point is called whenever a late fee is applied to an invoice for being overdue
-'''Variables'''
-*invoiceid
-====InvoicePaymentReminder====
-This hook point is called when Invoice Payment Reminder or Overdue Notices are sent to the client by the daily cron
-'''Variables'''
-*invoiceid
-*type - reminder, firstoverdue, secondoverdue, thirdoverdue
-===Support Tickets===
- TicketOpen - ticketid, userid, deptid, deptname, subject, message, priority
- TicketAdminReply - ticketid, replyid, deptid, deptname, subject, message, priority
-              admin, status
- TicketUserReply - ticketid, replyid, userid, deptid, deptname, subject, message
-              priority, status
- TicketOpenAdmin - ticketid, userid, deptid, subject, message, priority
- TicketAddNote = ticketid, message, adminid
-===Admin===
- AdminLogin - adminid
- AdminLogout - adminid
- AdminHomepage - none, can accept a return of HTML output
- AdminAreaClientSummaryPage - none, can accept a return of HTML output
- AnnouncementAdd - announcementid, date, title, announcement, published
- AnnouncementEdit - announcementid, date, title, announcement, published
- NetworkIssueAdd - id, startdate, enddate, title, description, type, server, affecting,
-              server, priority, status
- NetworkIssueEdit - same as above
- NetworkIssueClose - id
- NetworkIssueReopen - id
- NetworkIssueDelete - id
- ProductEdit - pid, name, description, etc...
- ProductDelete - pid
- AdminClientFileUpload - userid, title, filename, origfilename, adminonly
-===Miscellaneous===
- ClientAreaHomepage - none, can accept a return of HTML output
- ViewOrderDetailsPage - can be used to run code & output in order details view (eg. custom
-              fraud checks) - orderid, ordernum, amount, paymentmethod, invoiceid, status
- ClientAreaPage - can reference $smarty for defining template vars (no variables)
- AffiliateActivation - affid, userid
- EmailPreSend - messagename, relid (accepts an array return
- DailyCronJob - can be used to run code daily for custom processes (no variables)

Documentation

Difference between revisions of "Hooks"

Revision as of 15:58, 5 July 2011

How It Works

Hook Points