How to Create Custom Events in the WordPress Activity Log

You are here:
Back to KB search

Keep a Record of Any WordPress Change You Want in the WordPress Audit Trail

This document explains how you can build a sensor  and create custom alerts in WP Security Audit Log plugin to keep track of any type of change on your WordPress. Therefore now you can easily monitor changes on your WordPress that an out of the box installation of the plugin does not.

Introduction to the Process of Creating a Custom Events in the WordPress Audit Trail

WP Security Audit Log Sensors

For every set of changes, WP Security Audit Log has a sensor. For example to monitor all the login and logouts on WordPress, the plugin’s sensor is called LogInOut.php. All sensor files can be found in the following plugin directory:  /wp-security-audit-log/classes/sensors/. 

Note: Custom sensors should be stored in the /wp-content/uploads/wp-security-audit-log/custom-sensors/ directory so they are not overwritten during plugin updates.

The Events

If you are not familiar with events, first read the document What are WordPress activity log events. All the Events that the plugin uses in the WordPress activity log are declared in the file defaults.php which can be found in the root directory of the plugin (/wp-content/plugins/wp-security-audit-log). Refer to the complete list of WordPress security alerts for more information on the alerts.

Custom events should be declared in a file called custom-alerts.php which should be saved in the following directory: /wp-content/uploads/wp-security-audit-log/. Custom alerts are saved in another file so they are not overwritten during an upgrade.

The Process of Creating a Custom Event

Therefore the process of creating a custom event, or a number of custom events in the WordPress audit trail is very simple:

  1. Create a sensor in the /wp-content/uploads/wp-security-audit-log/custom-sensors/ directory
  2. Declare the alerts in the file /wp-content/uploads/wp-security-audit-log/custom-alerts.php. As simple as that. Let’s start

Read the rest of this post for more detailed explanation of how to build your sensor.

WP Security Audit Log Sensors Documentation and Sample Code

Before proceeding please download the file which includes the sample sensor file and custom alerts file used for the below example.

Developing the Sensor for WP Security Audit Log

Extract and open the sensor file WSAL_Sensors_CustomHooks.php from the zip file. The code in the sample sensor is fully documented  but just in case here is also a quick introduction. First you have to specify a class for your custom sensor:

Then specify the hooks you are going to use in this sensor in the section HookEvents, shown in the following code sample:

In the next and last part is where you should have the actual sensor code, i.e. the code that specifies what to monitor and what is the change that should generate the alert. In this section you should also specify the details about the WordPress security alert that is created in the WordPress audit trail, including the alert severity, alert code, alert text and any other variables that you want to use in the alert text.

Save and Name Your Sensor File

Once you’re ready with the code save the sensor file in the /wp-content/uploads/wp-security-audit-log/custom-sensors/ directory. The filename should always be the same as that of the class without the WSAL_Sensors_ prefix. So in this example the file is CustomHooks.php.

Declaring the Alerts in WP Security Audit Log

Once you create your sensor file, declare the alerts in the file custom-alerts.php which you can also find in the zip file you downloaded. The file should be saved in: /wp-content/uploads/wp-security-audit-log/. Below is the sample code for 3 alerts with different severity:

Once the custom alerts have been declared and the code is ready, navigate to the Enable/Disable Alerts nodes and you should be able to see your custom alerts in the Third Party Support tab, as seen in the below screenshot.

Custom alerts in WP Security Audit Log

Register Your Custom Events with Us

If you create your own sensor and custom events we recommend you to contact us and register your custom events, especially if you are creating events for a plugin or a component that is available to the public. By registering the events you ensure that it is not used by anyone else, hence avoiding conflicts.