Events

The event ingestion API turns external HTTP requests into Siren domain events. A POST to /event/{slug} looks up a registered factory by slug, builds the corresponding event from the request body, and broadcasts it through the same event system that powers WordPress-rendered traffic. Engagement triggers, conversion building, and obligation creation all run identically — the API is just a transport.

This is the primary interface a headless frontend, a connector plugin, or any non-WordPress runtime uses to participate in Siren’s attribution pipeline. The headless attribution guide walks through the most common usage end to end.

Endpoints

Method	Path	Description
POST	/event/site-visited	Report a site visit. Creates or updates an opportunity for a referred visitor.
POST	/event/sale	Report a sale. Creates a sale event from a non-WordPress checkout — typically used by the Siren Connect plugin or a custom commerce bridge.
POST	/event/refund	Report a refund. Reverses a previously reported sale by external ID.

Tier availability

The event ingestion controller lives in lib/Events, which ships with Essentials and above. Lite does not include it.

Authentication

In a WordPress install, the endpoint binds a no-op authentication middleware and defers to the WordPress REST permission chain. Out of the box that means the endpoint accepts unauthenticated POSTs — sufficient for site-visit tracking, where the form of the request itself encodes everything that matters. If your deployment needs stricter access control on a particular slug, wrap the endpoint with the same WordPress REST authentication mechanisms you’d use on any custom REST route (a filter on rest_pre_dispatch, a CORS plugin’s allowlist, an authenticated reverse proxy, etc.).

In a SaaS deployment the same controller binds an API-key middleware instead and requires a Bearer token with the appropriate scope.

Response shape

Every event-ingestion endpoint returns 200 OK with an empty body on success. The opportunity ID associated with the request — whether newly created or resolved from an inbound X-Siren-OID header or browser cookie — is written to the X-Siren-OID response header. The response also includes Access-Control-Expose-Headers: X-Siren-OID so JavaScript can read the value across origins.

Validation failures return 400 with the field errors. Unknown slugs return 404.

Adding new event factories

The factory registry is event-driven. An extension can listen for EventFactoryRegistryInitiated and call addFactoryClass(MyEventFactory::class) to register a new slug. The factory implements EventFactory, declares its slug, validation rules, and how to build a domain event from the request. The extension quickstart and event bindings and transformers cover the patterns.