Skip to content
Cloudflare Docs

Configure payload logging via API

Use the Rulesets API to configure payload logging for a managed ruleset via API.

Configure and enable payload logging

  1. Use the Get a zone entry point ruleset operation to obtain the following IDs:

    • The ID of the entry point ruleset of the http_request_firewall_managed phase.
    • The ID of the execute rule deploying the WAF managed ruleset, for which you want to configure payload logging.

  2. Use the Update a zone ruleset rule operation to update the rule you identified in the previous step.

    Include a matched_data object in the rule's action_parameters object to configure payload logging. The matched_data object has the following structure:

    "action_parameters": {
      // ...
      "matched_data": {
        "public_key": "<PUBLIC_KEY_VALUE>"
      }
    }

    Replace <PUBLIC_KEY_VALUE> with the public key you want to use for payload logging. You can generate a public key in the command line or in the Cloudflare dashboard.

Example

This example configures payload logging for the Cloudflare Managed Ruleset, which is already deployed for a zone with ID $ZONE_ID.

  1. Invoke the Get a zone entry point ruleset operation (a GET request) to obtain the rules currently configured in the entry point ruleset of the http_request_firewall_managed phase.

    Required API token permissions

     At least one of the following token permissions is required:
    • Response Compression Write
    • Response Compression Read
    • Config Settings Write
    • Config Settings Read
    • Dynamic URL Redirects Write
    • Dynamic URL Redirects Read
    • Cache Settings Write
    • Cache Settings Read
    • Custom Errors Write
    • Custom Errors Read
    • Origin Write
    • Origin Read
    • Managed headers Write
    • Managed headers Read
    • Zone Transform Rules Write
    • Zone Transform Rules Read
    • Mass URL Redirects Write
    • Mass URL Redirects Read
    • Magic Firewall Write
    • Magic Firewall Read
    • L4 DDoS Managed Ruleset Write
    • L4 DDoS Managed Ruleset Read
    • HTTP DDoS Managed Ruleset Write
    • HTTP DDoS Managed Ruleset Read
    • Sanitize Write
    • Sanitize Read
    • Transform Rules Write
    • Transform Rules Read
    • Select Configuration Write
    • Select Configuration Read
    • Bot Management Write
    • Bot Management Read
    • Zone WAF Write
    • Zone WAF Read
    • Account WAF Write
    • Account WAF Read
    • Account Rulesets Read
    • Account Rulesets Write
    • Logs Write
    • Logs Read
    • Logs Write
    • Logs Read
    Get a zone entry point ruleset
    curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/rulesets/phases/http_request_firewall_managed/entrypoint" \
      --request GET \
      --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"
    {
      "result": {
        "id": "060013b1eeb14c93b0dcd896537e0d2c", // entry point ruleset ID
        "name": "default",
        "description": "",
        "source": "firewall_managed",
        "kind": "zone",
        "version": "3",
        "rules": [
          // (...)
          {
            "id": "1bdb49371c1f46958fc8b985efcb79e7", // `execute` rule ID
            "version": "1",
            "action": "execute",
            "expression": "true",
            "last_updated": "2024-01-20T14:21:28.643979Z",
            "ref": "1bdb49371c1f46958fc8b985efcb79e7",
            "enabled": true,
            "action_parameters": {
              "id": "efb7b8c949ac4650a09736fc376e9aee", // "Cloudflare Managed Ruleset" ID
              "version": "latest"
            }
          }
          // (...)
        ],
        "last_updated": "2024-01-20T14:29:00.190643Z",
        "phase": "http_request_firewall_managed"
      },
      "success": true,
      "errors": [],
      "messages": []
    }

  2. Save the following IDs for the next step:

    • The ID of the entry point ruleset: 060013b1eeb14c93b0dcd896537e0d2c
    • The ID of the execute rule deploying the Cloudflare Managed Ruleset: 1bdb49371c1f46958fc8b985efcb79e7

    To find the correct rule in the rules array, search for an execute rule containing the ID of the Cloudflare Managed Ruleset ( ) in action_parameters > id.

  3. Invoke the Update a zone ruleset rule operation (a PATCH request) to update the configuration of the rule you identified. The rule will now include the payload logging configuration (matched_data object).

    Required API token permissions

     At least one of the following token permissions is required:
    • Response Compression Write
    • Config Settings Write
    • Dynamic URL Redirects Write
    • Cache Settings Write
    • Custom Errors Write
    • Origin Write
    • Managed headers Write
    • Zone Transform Rules Write
    • Mass URL Redirects Write
    • Magic Firewall Write
    • L4 DDoS Managed Ruleset Write
    • HTTP DDoS Managed Ruleset Write
    • Sanitize Write
    • Transform Rules Write
    • Select Configuration Write
    • Bot Management Write
    • Zone WAF Write
    • Account WAF Write
    • Account Rulesets Write
    • Logs Write
    • Logs Write
    Update a zone ruleset rule
    curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/rulesets/060013b1eeb14c93b0dcd896537e0d2c/rules/1bdb49371c1f46958fc8b985efcb79e7" \
      --request PATCH \
      --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
      --json '{
        "action": "execute",
        "action_parameters": {
            "id": "efb7b8c949ac4650a09736fc376e9aee",
            "matched_data": {
                "public_key": "Ycig/Zr/pZmklmFUN99nr+taURlYItL91g+NcHGYpB8="
            }
        },
        "expression": "true"
      }'

    The response will include the complete ruleset after updating the rule.

For more information on deploying managed rulesets via API, refer to Deploy a managed ruleset in the Ruleset Engine documentation.

Disable payload logging

To disable payload logging for a managed ruleset:

  1. Use the Update a zone ruleset rule operation (a PATCH request) to update the rule deploying the managed ruleset (an execute rule).

  2. Modify the rule definition so that there is no matched_data object in action_parameters.

For example, the following PATCH request updates rule with ID $RULE_ID deploying the Cloudflare Managed Ruleset so that payload logging is disabled:

Required API token permissions

 At least one of the following token permissions is required:
  • Response Compression Write
  • Config Settings Write
  • Dynamic URL Redirects Write
  • Cache Settings Write
  • Custom Errors Write
  • Origin Write
  • Managed headers Write
  • Zone Transform Rules Write
  • Mass URL Redirects Write
  • Magic Firewall Write
  • L4 DDoS Managed Ruleset Write
  • HTTP DDoS Managed Ruleset Write
  • Sanitize Write
  • Transform Rules Write
  • Select Configuration Write
  • Bot Management Write
  • Zone WAF Write
  • Account WAF Write
  • Account Rulesets Write
  • Logs Write
  • Logs Write
Update a zone ruleset rule
curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/rulesets/$RULESET_ID/rules/$RULE_ID" \
  --request PATCH \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --json '{
    "action": "execute",
    "action_parameters": {
        "id": "efb7b8c949ac4650a09736fc376e9aee"
    },
    "expression": "true"
  }'

For details on obtaining the entry point ruleset ID and the ID of the rule to update, refer to Configure and enable payload logging.