Event hooks let your module or theme respond to actions in FOSSBilling — like when a client signs up, an order is placed, or cron runs.
If you are building the module that will receive these hooks, start with Creating a Module.
How Hooks Work
Section titled “How Hooks Work”FOSSBilling fires events at key moments. You can register handlers to run your code when these events fire.
Hook names follow this pattern:
onBefore{Action}— Runs before the actiononAfter{Action}— Runs after the actiononEvent{Description}— Fires when a specific event occurs
The Hook module also supports onEveryEvent, a global listener that is connected to every fired event.
Admin Hooks
Section titled “Admin Hooks”Extensions
Section titled “Extensions”onBeforeAdminActivateExtensiononAfterAdminActivateExtensiononBeforeAdminDeactivateExtensiononAfterAdminDeactivateExtensiononBeforeAdminInstallExtensiononAfterAdminInstallExtensiononBeforeAdminUninstallExtensiononAfterAdminUninstallExtensiononBeforeAdminUpdateExtensiononAfterAdminUpdateExtensiononBeforeAdminExtensionConfigSaveonAfterAdminExtensionConfigSave
Clients
Section titled “Clients”onBeforeAdminClientCreateonAfterAdminClientCreateonBeforeAdminCreateClientonAfterAdminCreateClientonBeforeAdminClientDeleteonAfterAdminClientDeleteonBeforeAdminClientPasswordChangeonAfterAdminClientPasswordChangeonBeforeAdminClientUpdateonAfterAdminClientUpdate
Orders
Section titled “Orders”onBeforeAdminOrderActivateonAfterAdminOrderActivateonBeforeAdminOrderCancelonAfterAdminOrderCancelonBeforeAdminOrderCreateonAfterAdminOrderCreateonBeforeAdminOrderDeleteonAfterAdminOrderDeleteonBeforeAdminOrderRenewonAfterAdminOrderRenewonBeforeAdminOrderSuspendonAfterAdminOrderSuspendonBeforeAdminOrderUncancelonAfterAdminOrderUncancelonBeforeAdminOrderUnsuspendonAfterAdminOrderUnsuspendonBeforeAdminOrderUpdateonAfterAdminOrderUpdateonBeforeAdminBatchSuspendOrdersonAfterAdminBatchSuspendOrdersonBeforeAdminBatchCancelSuspendedOrdersonAfterAdminBatchCancelSuspendedOrders
Invoices
Section titled “Invoices”onBeforeAdminInvoiceApproveonAfterAdminInvoiceApproveonBeforeAdminInvoiceDeleteonAfterAdminInvoiceDeleteonBeforeAdminInvoiceRefundonAfterAdminInvoiceRefundonBeforeAdminInvoiceSendReminderonBeforeAdminInvoiceSendRemindersonAfterAdminInvoiceReminderSentonBeforeAdminInvoiceUpdateonAfterAdminInvoiceUpdateonAfterAdminInvoicePaymentReceivedonBeforeAdminGenerateRenewalInvoiceonAfterAdminGenerateRenewalInvoiceonEventBeforeInvoiceIsDueonEventAfterInvoiceIsDue
Subscriptions
Section titled “Subscriptions”onAfterAdminSubscriptionCreateonAfterAdminSubscriptionDelete
Transactions
Section titled “Transactions”onBeforeAdminTransactionCreateonAfterAdminTransactionCreateonBeforeAdminTransactionProcessonAfterAdminTransactionProcessonBeforeAdminTransactionUpdateonAfterAdminTransactionUpdate
Tickets
Section titled “Tickets”onBeforeAdminOpenTicketonAfterAdminOpenTicketonAfterAdminCloseTicketonAfterAdminReplyTicketonBeforeAdminPublicTicketOpenonAfterAdminPublicTicketOpenonAfterAdminPublicTicketCloseonAfterAdminPublicTicketReply
onBeforeAdminStaffCreateonAfterAdminStaffCreateonBeforeAdminStaffDeleteonAfterAdminStaffDeleteonBeforeAdminStaffPasswordChangeonAfterAdminStaffPasswordChangeonBeforeAdminStaffApiKeyChangeonAfterAdminStaffApiKeyChangeonBeforeAdminStaffUpdateonAfterAdminStaffUpdateonBeforeAdminStaffProfileUpdateonAfterAdminStaffProfileUpdateonBeforeAdminStaffProfilePasswordChangeonAfterAdminStaffProfilePasswordChange
System
Section titled “System”onBeforeAdminCronRunonAfterAdminCronRunonBeforeAdminDeleteCurrencyonAfterAdminDeleteCurrencyonBeforeAdminSettingsUpdateonAfterAdminSettingsUpdateonAfterAdminNotificationAddonBeforeAdminUpdateCoreonAfterAdminUpdateCoreonBeforeAdminManualUpdateonAfterAdminManualUpdate
Themes
Section titled “Themes”onBeforeThemeSettingsSave
Authentication
Section titled “Authentication”onBeforeAdminLoginonAfterAdminLoginonEventAdminLoginFailedonBeforePasswordResetStaffonAfterPasswordResetStaff
Client Hooks
Section titled “Client Hooks”Account
Section titled “Account”onBeforeClientSignUponAfterClientSignUponBeforeClientLoginonAfterClientLoginonEventClientLoginFailedonBeforeClientProfileUpdateonAfterClientProfileUpdateonBeforeClientProfilePasswordChangeonAfterClientProfilePasswordChangeonBeforeClientProfilePasswordResetonAfterClientProfilePasswordResetonBeforePasswordResetClient
Orders and Cart
Section titled “Orders and Cart”onBeforeProductAddedToCartonAfterProductAddedToCartonBeforeClientCheckoutonAfterClientOrderCreate
Tickets and Domains
Section titled “Tickets and Domains”onBeforeClientOpenTicketonAfterClientOpenTicketonAfterClientCloseTicketonAfterClientReplyTicketonBeforeClientChangeNameserversonAfterClientChangeNameservers
Guest Hooks
Section titled “Guest Hooks”onBeforeGuestPasswordResetRequestonBeforeGuestPublicTicketOpenonAfterGuestPublicTicketOpenonAfterGuestPublicTicketCloseonAfterGuestPublicTicketReply
Product Hooks
Section titled “Product Hooks”Service License
Section titled “Service License”onBeforeServicelicenseResetonAfterServicelicenseReset
Using Hooks in Your Module
Section titled “Using Hooks in Your Module”Define static methods in your module's Service.php:
class Service{ public static function onAfterAdminOrderCreate(\Box_Event $event): void { $order = $event->getSubject(); error_log('New order created: ' . $order->id); }
public static function onBeforeAdminCronRun(\Box_Event $event): void { }}FOSSBilling automatically discovers and calls these hooks when the events fire.
Troubleshooting Hook Discovery
Section titled “Troubleshooting Hook Discovery”FOSSBilling discovers hook methods when cron jobs run. If you add a new hook handler in a module, cron must run at least once before the hook is registered.
If a new hook is not being called:
- Confirm cron is configured and running correctly.
- During development, run cron jobs manually once after adding or renaming hook methods.
- Make sure the hook method is public and accepts a
\Box_Eventargument.