CustomEventTriggered

CustomEventTriggered is Siren’s headless integration mechanism. It fires when a custom event is ingested through the event API, making it the primary integration point for SaaS applications, non-ecommerce platforms, and any system that does not have a dedicated Siren extension. If your platform can send an HTTP request, it can participate in Siren’s attribution and conversion pipeline through this event.

The event ID is custom_event_triggered, and its fully qualified class is Siren\CustomEvents\Core\Events\CustomEventTriggered.

What does this event carry?

The event carries three things: an opportunityId that links the custom event back to a tracked customer session, an eventSlug that identifies the type of event being reported, and a data array containing any additional context the caller provided.

use Siren\CustomEvents\Core\Events\CustomEventTriggered;

public function handle(Event $event): void
{
    $opportunityId = $event->getOpportunityId();
    $eventSlug = $event->getEventSlug();
    $data = $event->getData();

    // The event slug identifies what happened.
    // The data array carries whatever context the external
    // system included in the API request.
}

How does it enter the conversion pipeline?

The InitializeConversionFromCustomEvent listener handles this event. It takes the opportunity ID and event data and feeds them into the standard conversion pipeline, where programs are evaluated, incentive rules are applied, and obligations are created. From that point forward, the flow is identical to what happens when a WooCommerce sale or an EDD purchase triggers a conversion.

This design means that headless integrations get the full power of Siren’s attribution, multi-program evaluation, and fulfillment system without needing a platform-specific extension. The external system only needs to track the opportunity ID from the initial referral and send it back when the conversion-worthy action occurs.

For the full lifecycle of system events and how they connect to the rest of Siren’s architecture, see the System Events overview.