System and Collaborator Events

This page covers events that operate outside the core conversion and payment pipelines. These include the collaborator registration flow, organization lifecycle events, the custom event system for headless integrations, LMS integration events, and the recipe import system. The events span several domains: Siren\Collaborators\Core\Events, Siren\Organizations\Core\Events, Siren\CustomEvents\Core\Events, Siren\LMS\Core\Events, and Siren\Recipes\Core\Events.

Collaborator registration flow

Collaborator events track the lifecycle of a new collaborator joining the system. The flow moves through three stages: a submission is received, the submission is processed, and the collaborator’s account becomes ready.

CollaboratorSubmissionReceived fires when a new collaborator registration request arrives. It gives listeners the opportunity to modify or enrich the submission before the collaborator record is created. A listener could auto-assign the collaborator to programs based on a referral code or set default field values based on the source.

CollaboratorAccountReady fires when a collaborator’s account is fully set up and ready to use. This event fires after all submission processing is complete and the account has been activated. It is the signal that the collaborator can now participate in programs and receive attribution.

Organization events

Organization events fire when tenant records are created or modified. OrgCreated fires when a new organization is provisioned, and OrgUpdated fires when an existing organization’s record changes. These are straightforward lifecycle notifications used for resource provisioning, default configuration setup, and admin alerts.

Custom events

Custom events are Siren’s headless integration mechanism. They allow external systems to trigger conversions through a simple API call without needing a platform-specific integration or e-commerce plugin.

CustomEventTriggered fires when a custom event is ingested through Siren’s event API. The event slug determines which programs can match the event, and the data array provides context that listeners or incentive resolvers can use to make decisions. This is the primary integration point for headless setups where the customer-facing application is not a supported e-commerce platform. A SaaS application can call the event API when a user completes an action and let Siren handle the attribution and reward calculation from there.

LMS events

LMS events fire when students complete lessons or courses in a connected learning management system. These events power engagement tracking for education-based incentive programs, where collaborators earn rewards based on student progress.

StudentCompletedLesson fires when a student finishes a lesson. The educator array carried by the event determines which collaborators receive engagement credit for the completion. A structurally similar StudentCompletedCourse event fires for full course completions and typically triggers larger rewards.

Recipe import

The recipe system allows pre-built program configurations to be applied to a Siren installation through a single event.

RecipeApplyRequested fires when a recipe should be applied to the current installation. The event is mutable: as handlers process different parts of the recipe, they record the created entities back onto the event so that later handlers can reference them. This allows complex configurations with cross-references between programs, program groups, and distributors to be applied in a single pass.