Triggers

Triggers are asynchronous events that can be fired by MonetizationOS (system triggers) or called programmatically from within workflows (custom triggers).

Triggers initiate background processing through associated event handlers, such as triggering actions in other systems.

By default, MonetizationOS offers the following system triggers:

• Counters Updated: Fires when writing any counter data for a user, triggered at the end of the request. Includes a list of counter updates.
• Decision: Fires at the end of a surface decision or access check, including the same information from the API response.
• Plans Changed: Fires when changing the brand record by adding or removing plans, triggered at the end of the request. Includes a list of plans added and plans removed.
• User Added: Fires when writing data for a user for the first time for a brand, triggered at the end of a request.

You can also choose to add custom triggers as needed. To begin, navigate to the Triggers section, in the left-hand navigation menu.

Your triggers page shows a list of configured triggers and allows you to edit and delete existing triggers, or add new ones.

Create the Trigger

To add a trigger, click 'Add a Trigger'.

You will be prompted to give your trigger a name, slug and optional description. By default, the slug will be a hyphenated version of the name you give the trigger, but you can override this if you wish.

If you have Brands enabled, you must link this trigger to a particular brand or brands, by clicking the 'Link Brands' button. This means the trigger will only be available in environments linked to that specific brand or brands.

Once done, click 'Create Trigger'. You will then be taken to the trigger management area. This is separated into three tabs: Schema, Actions, and Manage.

Schema

The Schema tab allows you to define the structure and types of data that your trigger will send when it fires. This serves a few purposes:

• Data Contract: The schema acts as a contract between the trigger and any event handlers that listen to it. When you define a schema, you're telling other workflows exactly what data they can expect to receive.
• Type Safety: Event handlers can reference the schema to know what properties are available and what types they are, reducing errors and improving development experience.
• Documentation: The schema serves as built-in documentation for other developers who want to create actions for your trigger.

To set the schema, write a TypeScript interface that describes your trigger's data structure. You must export exactly one interface from the schema file.

If you leave the schema empty, the trigger will accept any data type.

When creating actions for this trigger, you'll be able to see and use your defined schema.

Example

Your schema might look something like:

// Trigger schema
export interface MyData {
  name: string;
}

When event handlers process this trigger, they know exactly what data structure to expect and can access the relevant properties accordingly.

Actions

The Actions tab lists any actions that are fired by your trigger. This list includes the action name and description, linked brands, and provides the ability to edit or delete actions.

To create a new action that responds to this trigger, click 'Add an Action'. For more information on creating actions, see our Actions guide.

Manage

The Manage tab allows you to edit the name, slug, description, and linked brands of your trigger.

You can also toggle whether the trigger is user scoped. When this is enabled, the trigger must be called with an identity parameter, meaning it's tied to a specific user - for example, "user completed onboarding", or "user upgraded plan". When this is not enabled, the trigger can be called without an identity parameter, making it a global event - for example, "daily-report-generated".

You can also delete your trigger from this tab.

Editing a Trigger

To edit a trigger, locate it in your trigger list, then click the 'Edit' icon in the actions column.

This will bring up the same screen you used to configure your trigger. Make any relevant changes, and click 'Update'.

Deleting a Trigger

To delete a trigger, locate it in your trigger list, then click the 'Delete' icon in the actions column.

You will be prompted to confirm you wish to remove the trigger. This action cannot be undone.

To continue, click 'Delete'. Otherwise, click 'Cancel'.