Notifications

Overview

WHMCS integrates with popular team communication apps including Slack and HipChat to allow you to be notified in real-time as events occur within WHMCS.

Using conditions, you can setup WHMCS to notify you in your Slack channels and HipChat rooms about the events that are important to you. Here are some examples.

Notify my Support channel/room when a new ticket is opened in the Support department with a High priority
Notify my Enterprise Support channel/room when a new ticket is opened or replied to by a customer belonging to the Enterprise Customers client group
Notify my Emergency channel/room when a new ticket is opened containing the words "Emergency" in the subject
Notify my Sales channel/room when a new order is placed with a value over $25
Notify my Billing channel/room when an invoice is paid by a customer belonging to the High Value client group
Notify my Customer Service channel/room when an order is placed for the product Business Hosting

Configuring Notification Providers

At the time of writing, WHMCS supports the following notification providers out of the box. Select one to learn more and for information on how to configure it.

You can add additional notification providers by creating a custom notification module. You can learn more about that here: https://developers.whmcs.com/notification-providers/

Creating a Notification Rule

Notifications are based around rules.

Each rule defines when a notification should be triggered through a combination of events and conditions.

To create a new rule, follow the steps below.

1. Click the Create New Notification Rule button.
2. Enter a name/description for your rule that will allow you to easily identify it again later.
3. Choose an Event Category from the available selector buttons.

4. Choose one or more events that should trigger the notification within the selected event category. Use Ctrl+click to select multiple ones.
5. Configure any conditions you want to use to restrict when the notification is triggered. The conditions available to you will vary based on the selected event category.

By default all conditions default to unrestricted. To apply a condition to a rule, simply select or provide a value for a given condition. In the case of a free text based condition such as Subject, you are given the option of choosing from an Exact Match or Containing Match. In a monetary value condition such as Order Total, you have the option of specifying a Greater Than or Less Than match.

6. Configure the desired Notification Settings:

i. Begin by choosing the desired notification provider for this rule. Here we have chosen HipChat.
ii. The other options here will depend upon the notification provider selected, but in the case of both HipChat and Slack, you will be asked to choose a Room/Channel for the notification to be posted to and be given the ability to override the default message with a custom one of your choosing.
iii. In the case of HipChat, you also have the ability to select whether the notification should trigger an alert for the user. When selected, this can include playing a sound, a mobile notification, and more based on an individual users notification settings.

Modifying a Notification Rule

To edit a notification, locate the notification rule you wish to edit and click the pencil icon.

This will open the rule configuration dialog where you can make your desired changes.

For more information on the configuration options that are available, please refer to the Creating a Notification Rule guide.

Duplicating a Notification Rule

To duplicate a notification, locate the notification rule you wish to copy and click the copy icon (indicated by two files).

This will open the rule configuration dialog where you can customise the rule and then click the Duplicate button to complete the process.

For more information on the configuration options that are available, please refer to the Creating a Notification Rule guide.

Enabling/Disabling a Notification Rule

The current status of each notification rule is indicated within the Notification Rules table by an on/off slider.

To toggle the status of a notification, simply click the slide toggle for the desired notification rule.

Deleting a Notification Rule

To delete a notification, locate the notification rule you wish to edit and click the trash can icon.

You will be asked to confirm you are sure you want to delete the rule before it is removed.

Please note that a rule cannot be restored after it has been deleted so if you may want to re-use the rule in future, we recommend disabling the rule instead of deleting it.

Hooks

Using hooks, it is possible to implement more complex conditional logic than is possible with the conditions available via the Admin Area (Setup >> Notifications).

WHMCS makes available a "NotificationPreSend" hook point which executes prior to a notification being sent to allow for additional conditional criteria to be applied and manipulation of the notification message. This hook point can also be used to abort the sending of a Notification based on your logic.

<?php

add_hook('NotificationPreSend', 1, function($vars) {

    $eventType = $vars['eventType']; // e.g. "Ticket", "Invoice", "Order", "Service" or "Domain"
    $eventName = $vars['eventName'];
    $rule = $vars['rule'];
    $hookParameters = $vars['hookParameters'];
    $notification = $vars['notification'];

    // Perform additional conditional logic and throw the AbortNotification
    // exception to prevent the notification from sending.
    if ($eventType == 'Invoice'
        && $eventName == 'created'
        && (isset($hookParameters['invoiceid'])
        && $hookParameters['invoiceid'] > 1000)
    ) {
        throw new \WHMCS\Notification\Exception\AbortNotification();
    }

    // If allowing the notification to continue, you can manipulate the
    // notification using the \WHMCS\Notification\Notification object.
    $notification->setTitle('Override notification title');
    $notification->setMessage('Override notification message body');

});

By implementing the above hook, any notification for an invoice created with an ID above 1000 will abort the notification being sent. Aborting a notification is achieved by throwing a `\WHMCS\Notification\Exception\AbortNotification();` exception.

If the ID is below 1000, the notification will continue to be sent however, the title and message will be overrided. Overriding values can be achieved using the "set" functions made available to you via $notification with more information on those available being found in our Internal Class Documentation, here.

API

WHMCS makes available an API function called TriggerNotificationEvent which allows you to leverage the Notifications system within WHMCS to send notifications on-demand.

Below is an example of using this API method to trigger a notification whenever an admin user logs in to the Admin Area. This can be achieved using a combination of the "AdminLogin" hook and the TriggerNotificationEvent API call like so:

<?php
add_hook('AdminLogin', 1, function($vars) {

    $command = 'TriggerNotificationEvent';
    $postData = array(
        'notification_identifier' => 'adminarea.staff.login', // A unique identifier used when referencing the notification rule.
        'title' => 'A Staff Member Just Logged In',
        'message' => $vars['username'] . ' just logged in to the WHMCS Admin Area.',
        'url' => 'https://whmcs.example.test/admin/',
        'status' => 'Success',
        'statusStyle' => 'info',
    );
    $adminUsername = 'ADMIN_USERNAME'; // Optional for WHMCS 7.2 and later
    $results = localAPI($command, $postData, $adminUsername);
    print_r($results);
});

Once your API call has been created, you next need to navigate to Setup > Notifications in the WHMCS Admin Area and define a rule for this event.

From the WHMCS Admin Area, navigate to Setup > Notifications

Click "Create New Notification Rule"

Type a name for your Notification Rule

Select "API" and "Custom API Trigger"

Under "Trigger Identifier", input the notification identifier you specified in the API Call. In our example, this is "adminarea.staff.login".

Select "Exact Match" in the select element above

Finally, select and configure the notification method. For example, in the screenshot below we are configuring an Email notification to login-notifications@example.net

Once setup, whenever this API call is triggered, a custom notification will be delivered via your chosen Notification provider.

Adding a Custom Notification Provider

You can add additional notification providers that notification rules can use by creating a custom notification module. You can learn more about that here: https://developers.whmcs.com/notification-providers/