Event Context and Options

The third argument to sp_capture() is an options array merged into event context. Context travels with the event to integrations, appears in delivery log previews, and powers routing filters.

See Capturing Events with sp_capture() for the basic call shape.

Common options

Option	Purpose
source	Where the event originated (plugin, cron job, hook name)
services	Limit delivery to specific integration IDs — Service Targeting
environment	Override the site-wide environment for this event
event_id	Unique ID for this capture call (auto-generated if omitted)
correlation_id	Tie related work together across requests
distinct_id	Product analytics identity (PostHog and similar)
user_id	Provider-specific user field (for example GA4)
client_id	Client identifier when applicable
session_id	Session identifier when applicable
wp_user_id	WordPress user ID for the current request

Capture origin (free)

When Capture origin is enabled under SignalPress → Settings, SignalPress adds these optional context fields automatically for PHP captures:

Field	Purpose
capture_component	Caller label (plugin:slug, theme:slug, mu-plugin:file, …)
capture_file	Relative file path
capture_line	Line number
capture_function	Calling function or method

See Capture Origin for log columns, JavaScript behavior, and which integrations receive the fields.

Unknown keys remain available in context for custom integrations and Hooks and Filters.

WordPress user ID

When a logged-in user triggers a capture, SignalPress automatically adds numeric wp_user_id to context. It does not add username, email, display name, or roles.

• Pass an explicit wp_user_id option to override the detected value
• Pass 0 to suppress it for a single event

wp_user_id is separate from provider fields such as GA4’s user_id or PostHog’s distinct_id. JavaScript capture and Client-side analytics use separate browser channels.

Source

Describe where the event originated:

PHP

sp_capture(
	'exercise_milestone_reached',
	$milestone,
	[ 'source' => 'action:mt_exercise_milestone_reached' ]
);

Routing rules can filter on source. The Test Shortcode sets shortcode:signalpress_test.

Project and environment defaults

Site-wide Project and Environment values come from Setup & Activating SignalPress. SignalPress also adds project, environment, request_id, and the three event identifiers to every capture automatically unless you override them in the options array.

Per-event overrides can be passed in the options array when an integration supports them.

Remote delivery blocks

If the SignalPress hub puts a site in read-only or disabled operation mode, capture returns WP_Error before any service handoff. Unchecking Event delivery in Settings returns an empty array instead.

Validation and rejection

SignalPress validates every event before dispatch. These conditions return WP_Error and fire the signalpress/rejected action:

• Recursive or unsupported property values
• Excessive nesting
• JSON encoding failures
• Encoded payloads above the default 1 MB limit

Adjust the limit with the signalpress/max_payload_bytes filter (Tier 1+ — Hooks and Filters). Rejected events are not sent to services and not written to the delivery ledger.

Event IDs

Every PHP capture receives three identifiers automatically:

• event_id — unique to one capture call
• request_id — shared by all captures in the same WordPress request
• correlation_id — defaults to event_id; supply your own to link workflows

Use correlation IDs with the Tier 2 delivery queue when retrying failed handoffs.

What to read next

• Capture Origin — trace PHP capture calls in logs and observability tools
• Service Targeting — limit destinations with services
• Hooks and Filters — transform properties, context, and destinations (Tier 1+)
• Your First Connection Test — confirm context shows up in logs
• Advanced Event Routing — filter on source, environment, and patterns
• Free vs SignalPress Pro — tier gates for hooks and payload filters