Tracking endpoints

Burst uses two tracking methods to record page hits: a standalone PHP beacon file and a WordPress REST API fallback route. Burst selects between them automatically based on a connectivity test run at plugin load.

Beacon endpoint

The primary tracking endpoint. It bootstraps WordPress with SHORTINIT for minimal overhead and records hits directly, bypassing the full REST API stack.

URL: {plugin_url}/burst-statistics/endpoint.php Method: POST Content-Type: application/x-www-form-urlencoded Authentication: none

Test request

Send request=test to verify the endpoint is reachable. Returns HTTP 200 on success.

Show code

$response = wp_remote_post(
    plugins_url( 'endpoint.php', BURST_FILE ),
    [
        'method'    => 'POST',
        'headers'   => [ 'Content-type' => 'application/x-www-form-urlencoded' ],
        'body'      => [ 'request' => 'test' ],
        'sslverify' => false,
    ]
);

CORS (cross-origin support)

By default the beacon only accepts same-origin requests. To allow hits from a different domain, define BURST_ALLOWED_ORIGINS in wp-config.php as a comma-separated list of hostnames. Entries may optionally include a scheme — the scheme is stripped before comparison, so https://app.example.com and app.example.com are both accepted:

define( 'BURST_ALLOWED_ORIGINS', 'app.example.com,cdn.example.com' );

Changed in v3.4.0: entries may now include a scheme (e.g. https://app.example.com); the scheme is stripped before comparing against the request's HTTP_ORIGIN host.

When the constant is defined:

1. The request's HTTP_ORIGIN is checked against the list (host-only comparison)
2. If it matches, Access-Control-Allow-Origin is reflected, credentials are allowed, and POST and OPTIONS methods are permitted
3. If it does not match, the endpoint returns HTTP 403 and exits

caution

Any origin not listed in BURST_ALLOWED_ORIGINS (or BURST_HEADLESS_DOMAIN) is rejected when either constant is defined. Leave both constants undefined to keep the default same-origin-only behaviour.

Preflight OPTIONS requests receive HTTP 204 with Access-Control-Max-Age: 3600.

Headless domain allow-list

Added in v3.4.0: when BURST_HEADLESS_DOMAIN is defined, its host is automatically appended to the beacon's allowed origin list alongside any hosts from BURST_ALLOWED_ORIGINS. Defining BURST_HEADLESS_DOMAIN on its own is sufficient to allow the headless front-end to post to the beacon — you do not need to duplicate the domain in BURST_ALLOWED_ORIGINS.

define( 'BURST_HEADLESS_DOMAIN', 'https://app.example.com' );

When BURST_HEADLESS_DOMAIN is defined, the frontend tracking script (burst.js) is not enqueued on the WordPress site itself — the headless client is expected to load the script on the remote front-end instead. See Integrations for the headless client plugin flow.

POST burst/v1/track

Fallback tracking route used when the standalone endpoint.php beacon is unreachable — for example when aggressive server-side caching or rewrite rules block direct PHP file access.

Route: burst/v1/track Method: POST Content-Type: application/json Authentication: none (permission_callback is __return_true)

Test request

Show code

$response = wp_remote_post(
    get_rest_url( null, 'burst/v1/track' ),
    [
        'headers'     => [ 'Content-Type' => 'application/json; charset=utf-8' ],
        'method'      => 'POST',
        'body'        => wp_json_encode( [ 'request' => 'test' ] ),
        'data_format' => 'body',
        'timeout'     => 5,
    ]
);

HTTP 200 indicates the REST route is reachable and Burst will use it as the active tracking method.

Headless client routes

Added in v3.4.0. When BURST_HEADLESS_DOMAIN is defined, two additional REST routes are registered for the Burst Client plugin running on the headless front-end. Both routes authenticate via a bearer token issued when the client plugin zip is generated, and additionally verify that the request's Origin or Referer header matches the configured headless domain.

Authentication

Both routes require a bearer token in the Authorization header:

Authorization: Bearer <token>

The token is generated once when an administrator downloads the Burst Client plugin zip from Settings → Advanced → Download Burst Client plugin. Only the SHA-256 hash of the token is stored in the burst_headless_token_hash option — the raw token lives only inside the generated zip. Generating a new zip rotates the token and invalidates any previously distributed client plugin.

In addition to the token, the request's Origin (or fallback Referer) header must match BURST_HEADLESS_DOMAIN. Subdomains of the allowed host are accepted. Requests that fail either check return HTTP 403.

GET burst/v1/client/hooks/get

Returns the list of hook names for goals configured with type: hook. The headless client uses this to know which PHP actions to forward as goal completions.

Route: burst/v1/client/hooks/get Method: GET Authentication: bearer token + origin/referer check

Show code

$response = wp_remote_get(
    get_rest_url( null, 'burst/v1/client/hooks/get' ),
    [
        'headers' => [
            'Authorization' => 'Bearer ' . $token,
            'Origin'        => 'https://app.example.com',
        ],
        'timeout' => 5,
    ]
);

Response on success:

Show code

{
    "request_success": true,
    "hooks": [ "woocommerce_order_status_completed", "custom_goal_hook" ]
}

POST burst/v1/client/register_hook

Registers a goal conversion triggered by a hook on the headless front-end. The client sends the hook name plus the visitor's burst_uid cookie value; the WordPress side resolves the matching goal and records the conversion.

Route: burst/v1/client/register_hook Method: POST Authentication: bearer token + origin/referer check

Parameters:

Name	Type	Description
hook	string	The hook name fired on the headless front-end. Must match a goal with type: hook
uid	string	The visitor's burst_uid — on a headless setup the UID is posted through the REST API rather than read from a cookie on the WordPress side

Show code

$response = wp_remote_post(
    get_rest_url( null, 'burst/v1/client/register_hook' ),
    [
        'headers'     => [
            'Authorization' => 'Bearer ' . $token,
            'Content-Type'  => 'application/json; charset=utf-8',
            'Origin'        => 'https://app.example.com',
        ],
        'body'        => wp_json_encode(
            [
                'hook' => 'woocommerce_order_status_completed',
                'uid'  => $burst_uid,
            ]
        ),
        'data_format' => 'body',
        'timeout'     => 5,
    ]
);

Response on success:

{
    "request_success": true
}

Tracking status

Burst\Frontend\Endpoint manages which method is active and stores the result in the burst_tracking_status WordPress option.

Value	Meaning
beacon	endpoint.php is reachable; primary method in use
rest	endpoint.php is not reachable; REST fallback in use
error	Neither method is reachable; no tracking is occurring

The status is re-tested automatically:

• Every 24 hours when status is beacon or rest
• Every 10 minutes when status is error (to recover faster after a hosting issue is resolved)

Overriding the re-test interval

Use the burst_time_between_tests filter to change how frequently Burst re-tests:

Show code

add_filter( 'burst_time_between_tests', function( int $time_between_tests ): int {
    // Re-test every 6 hours regardless of status.
    return 6 * HOUR_IN_SECONDS;
} );

Filter parameters:

Parameter	Type	Description
$time_between_tests	int	Seconds between connectivity tests. Default: DAY_IN_SECONDS (86400) when tracking is working; 10 * MINUTE_IN_SECONDS (600) when status is error