Development Guides Home

Guide to Report Receiver APIs for the ModSecurity Rule Reports


This document describes report receiver API endpoints for the ModSecurity™ Rule Reports. cPanel & WHM provides an API to transmit ModSecurity™ rule hits to a customizable URL. The report function allows rule distributors to receive feedback about problems that users encounter with their ModSecurity rules.


This document is for ModSecurity vendors, such as OWASP, rather than cPanel & WHM developers.

Set the endpoint URL

Each vendor requires a metadata file. This file contains the information that the WHM API 1 uses to identify the rules, where to download those rules, and the report URL.

For more information about how to set the report receiver endpoint URL, read our Create a ModSecurity Vendor documentation.

Implement an API endpoint

Make certain that your report receiver endpoint accepts the following request and response data pair:


The report sender API provides the request data.

HTTP Details

Details Description
Path to API endpoint You can customize the endpoint URL to meet your individual needs.
Methods accepted POST
Request body Content-Type application/json

Body Details

Type Description
hits array
      meta_id integer The unique ID number, as the id action of the ModSecurity rule specifies it.
      id integer The line number from the modsec database.
     ip string The client's source IP address.
     http_version string The Hypertext Transfer Protocol (HTTP) version number.
      meta_line integer The line number of the rule that generated the hit within the ModSecurity configuration file.
      timestamp string The time of the hit.

This parameter uses the server's configured time zone.
      meta_uri string The client-requested URI.

This data is not always available.
      http_method string The HTTP method that the client used to generate the hit.
      http_status integer The HTTP status code that the web server returned.
      timezone integer The server's configured timezone as a number of minutes offset from Greenwich Mean Time (GMT).
      meta_file string The file that contains the ModSecurity rule that generated the hit.
      action_desc string The text that the web server posted to the client.
      meta_logdata string The transaction data fragment from the ModSecurity rule's logdata action.
      path string The relative path to the virtual host's document root.
       host string The virtual host's domain name.
      handler string This parameter only returns null.
      meta_offset integer The byte offset where a match occurred within the target data.

This data is not always available.
      meta_rev integer The revision number from the ModSecurity rule's rev action.
      justification string The specific criteria from the ModSecurity rule that generated the hit.
      meta_severity string The hit severity level from the ModSecurity rule's severity action.
      meta_msg string The human-readable message from the ModSecurity rule's msg action.
      file_exists Boolean If the value is 1, the file that the meta_file parameter lists exists. If the value is 0, the file does not exist.
email string The email address that the submitter providers for future contact with the rule maintainers.
type string The type of report.

This field has no specified format. You can treat the field as freeform text.
message string A short message from the submitter about the rule's issue.
rule_text string The exact text of the rule at the time of submission.

You may encounter submissions of a report from an old hit, if the submission occurred after an update to the rule. Use the meta_rev field to track the rule revision that caused the problem.


The report receiver API provides the response data.

HTTP details

Status The status must always use 200 on success.

  • For any failure that still results in a JSON response, we recommend that you use a 200 status and the body to communicate the error. This status instructs the report sender API to attempt to parse the response.
  • For complete failure to use a relevant JSON response, use 4xx or 5xx error codes.
Response body Content-Type application/json

Body details

Output Type Details
status Boolean If the value is 1, the receiver accepted the report. If the value is 0, the receiver encountered an error.

string A short message about the error.

This value is optional unless an error occurs.