Web SDK POST-Only Mode for Beacon Events

By default, the Web SDK sends beacon events via HTTP GET with the event payload encoded in the URL query string. When usePostForEvents: true is set, the SDK switches to HTTP POST, placing the payload in the request body instead.

What Changes

How to Enable

Add usePostForEvents: true to your sitemap initialization config.

Evergage (legacy namespace) :

Via configure:
Evergage.configure(endpointConfig, {

Via init:

• When the flag is not set or is false: No change. The SDK continues to use GET by default, with automatic fallback to POST only for oversized (>8KB) or non-ASCII payloads. This is the existing behavior for all current customers.

• When the flag is true: All beacon requests use POST regardless of payload size.

Benefits of Enabling POST Mode

Event data not transmitted in URLs

With POST mode, event payloads (user identifiers, behavioral data, interaction details) are sent in the request body rather than in URL query parameters. Request bodies are not recorded by intermediate infrastructure such as load balancer access logs, corporate proxy logs, or browser history. This can simplify compliance with data handling policies that require minimizing where identifiable information is persisted.

No URL length constraints

GET requests are subject to URL length limits that vary by browser and infrastructure (typically 2KB–8KB). POST removes this constraint entirely, allowing richer event payloads without risk of truncation.

Simplified compliance posture

Organizations subject to security audits or data protection policies (GDPR, CCPA, PCI-DSS) may have requirements around how data appears in transit logs. POST mode satisfies policies that flag query-string transmission of identifiable data.

Considerations When Enabling POST Mode

Page exit event delivery

The SDK uses various techniques to ensure events fire reliably when a user navigates away from or closes a page. GET requests via image pixel have historically had strong browser support during page teardown. POST requests rely on navigator.sendBeacon() and keepalive fetch for the same reliability. These APIs are well-supported in modern browsers but are subject to a shared 64KB budget for in-flight keepalive requests. In most scenarios this is not a practical concern, but pages that fire a very high volume of simultaneous events during unload should be aware of this limit.

CORS preflight requests

POST requests with certain content types may trigger a CORS preflight (OPTIONS) request, adding one additional network round-trip before the actual event is sent. The SDK uses application/x-www-form-urlencoded to avoid preflight in most cases, but environments with custom CORS configurations should verify that beacon requests complete without issues.

Browser extension and proxy compatibility

GET image-pixel requests are generally less visible to ad blockers and browser extensions than XHR/fetch POST requests. In environments where users have aggressive content-blocking extensions, there is a small possibility that POST beacon requests may be intercepted. This is uncommon for first-party beacon domains but worth noting for completeness.

Content Security Policy (CSP)

GET image pixels require the beacon domain in img-src, while POST requests require it in connect-src. If your site uses a strict Content Security Policy, ensure the beacon domain is included in the connect-src directive.

Infrastructure log visibility

With GET, the full event payload is visible in load balancer access logs (e.g., AWS ALB logs queryable via Athena), which can be useful for debugging. With POST, access logs will show the endpoint path but not the request body. This is the intended behavior of the feature, but support and engineering teams should be aware that log-based debugging of specific events will require alternative approaches.

How to Verify

You can verify the setting is working by inspecting the browser Network tab:

1. Open DevTools and go to the Network tab.

2. Filter requests by the beacon endpoints: event, pr, msreceiver, or er.

3. Trigger SDK activity (navigate a page, wait for a ping timer, etc.).

4. Check:

   • Method column should show POST (not GET).

   • Request URL should have no query string payload (just the path).

   • Payload / Request Body tab should show the form-encoded event parameters.

Rollback

The flag is purely client-side and opt-in. To revert to GET behavior, remove usePostForEvents: true from the sitemap config and redeploy. No server changes are needed.