> For the complete documentation index, see [llms.txt](https://codemash.gitbook.io/codemash/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://codemash.gitbook.io/codemash/cloud/concepts/triggers.md). # Triggers React to events automatically — when something happens, run an action. One feature, five event sources, seven actions. > A **trigger** connects an event to an action: *when* something happens in your project, Norbix *then* runs an action for you — no polling, no extra code. For example: when a user registers, send a welcome email; when a record is inserted, call a webhook; when an order is paid, run a function; when a user has used 80 % of their AI plan, push "upgrade your plan" to them. ## What it is Triggers are a cross-cutting feature: the trigger shape, the actions and the run rules are built once, and five modules use them as **event sources**. Each source has its own events and its own save / get / enable / disable / delete endpoints; everything else is shared. ## The parts Every trigger has the same parts, whatever its source: 1. **When** — the event that fires it (for example `OnRegistered`, `OnInserted`, `OnOrderPaid`, `OnQuotaWarning`). The events of each source are listed below. 2. **Action** (`thenAction`) — what to run. The action is chosen by its `type` field; see the seven actions below. 3. **Delivery settings** — for the Email, SMS and Push actions: who receives the message (all users, account users, specific users, raw addresses / phone numbers / devices, or records from a collection) and which provider sends it. 4. **Name**, optional **Description**, **Enabled**, and an optional **pre-action code** (`activationCode`, the Razor code that decides whether the trigger runs). ### The five event sources | Source | Fires on | Events (`when`) | Event name for webhooks | | ------------------------------ | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | | **Membership** | user lifecycle | `OnRegistered`, `OnUserCreated`, `OnInvited`, `OnVerified`, `OnUpdated`, `OnDeleted`, `OnBlocked`, `OnReactivated` | `membership.user.registered`, `.created`, `.invited`, `.verified`, `.updated`, `.deleted`, `.blocked`, `.reactivated` | | **Database** (schema triggers) | records of one collection | `OnInserted`, `OnUpdated`, `OnDeleted` | `database.record.inserted`, `.updated`, `.deleted` | | **Files** | file storage | `OnFileUploaded`, `OnFileDeleted` | `files.file.uploaded`, `.deleted` | | **Payments** | orders and payment-provider callbacks | `OnOrderCreated`, `OnOrderPaid`, `OnWebhookCallReceived` | — | | **AI** | AI credits and AI plan quotas | `OnCreditsWarning` — the project used 80 % of the AI credits included this month · `OnCreditsExhausted` — 100 % · `OnQuotaWarning` — one end user used 80 % of their AI plan's monthly quota · `OnQuotaExhausted` — 100 % | `ai.credits.warning`, `ai.credits.exhausted`, `ai.quota.warning`, `ai.quota.exhausted` | ### The seven actions Any source can use any action: | Action | `type` | What happens | | -------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Send an email | `email` | Starts an [Email campaign](/codemash/cloud/concepts/campaigns.md) with one of your [email templates](/codemash/cloud/concepts/message-templates.md) | | Send a push notification | `push` | Starts a [Push campaign](/codemash/cloud/concepts/campaigns.md) with one of your push templates | | Send an SMS | `sms` | Starts an [SMS campaign](/codemash/cloud/concepts/campaigns.md) with one of your SMS templates | | Call a webhook | `webhookcall` | Publishes the event to your webhook destinations (in addition to the plain webhook of a destination subscribed to the same event — de-duplicate on `eventId`, see [Webhooks](/codemash/cloud/project/settings/webhooks.md#what-a-delivery-looks-like)) | | Run a function | `code` | Executes one of your functions from the **Code** module | | Send a realtime event | `ssecall` | Pushes a server-sent event to connected clients | | Run a marketplace function | `marketplace` | Runs an installed marketplace function | In Cloud the action picker offers six choices: **Run Code**, **Send Email**, **Send Push Notification**, **Send SMS**, **Call Webhook** and **Send In-App (Realtime / SSE)**. **Run Code** saves a `marketplace` action (an installed marketplace function); the `code` type is set through the API or an SDK. ## Rules that are the same everywhere * **Email, SMS and Push actions start a campaign.** When the trigger fires, Norbix creates a campaign of that channel from the action's template, audience and provider. It appears in the channel's campaign list like any other, with its batches and message log. See [Campaigns](/codemash/cloud/concepts/campaigns.md). * **The messaging actions follow the campaign rules.** The action names its **provider** (the portal pre-selects the project default; the server never falls back to it), its template needs a translation for every **project language**, an optional forced language must be a project language, and an optional **send on behalf of** user fills the `Initiator.User.*` tokens (empty = the user who saved the trigger). They are checked on save and enable, and again each time the trigger fires. * **Needs attention.** A run that cannot send for a reason you can fix (the template is gone, the provider is missing or off, the template misses a project language) marks the trigger **Needs attention** in its trigger list. The next good run, a save or a delete clears the mark. * **One failing trigger does not stop the others.** When a trigger's action fails, the failure is logged and the next trigger of the same event still runs. The event is not retried. * **What a trigger uses is protected.** A template that a trigger uses cannot be deleted or archived (`CM-ERRORS-TEMPLATES-010`), and an integration that a trigger uses cannot be deleted (`CM-ERRORS-INTEGRATIONS-019`). Change the trigger first. * **Tokens.** The event's data reaches the template as tokens (for example `@Model.Trigger.New`). Token binding covers the whole action, not only the template: the pre-action code is Razor too, so any `@Model.…` token it uses needs a value, exactly like a token in the subject, title, body or config. Until every token has one, the action cannot be sent. See [the token rule](/codemash/cloud/concepts/message-templates.md#the-token-rule) and [Tokens binding](/codemash/cloud/concepts/tokens-binding.md). ## Where it lives | Source | Portal page | SDK methods | API reference | | ---------- | -------------------------------------------------------------------------- | ------------------------------------------------------------ | -------------------------------------------------------------------------------------- | | Membership | [Membership → Triggers](/codemash/cloud/membership/triggers.md) | [Membership triggers](/codemash/sdks/membership/triggers.md) | [Membership triggers](/codemash/api-reference/membership/triggers.md) | | Database | [Schema triggers](/codemash/cloud/database/collections/schema-triggers.md) | [Schema triggers](/codemash/sdks/database/triggers.md) | [Save Schema Trigger](/codemash/api-reference/database/schemas/save-schema-trigger.md) | | Files | [Files → Triggers](/codemash/cloud/files/triggers.md) | [Files triggers](/codemash/sdks/files/triggers.md) | [Files triggers](/codemash/api-reference/files/triggers.md) | | Payments | [Payments → Triggers](/codemash/cloud/payments/triggers.md) | [Payments triggers](/codemash/sdks/payments/triggers.md) | [Payments triggers](/codemash/api-reference/payments/triggers.md) | | AI | none — API only | not in the SDK reference yet | not in the API reference yet — routes below | **AI triggers are API only.** Cloud has no screen for them. Use the six routes directly: `POST /{version}/ai/triggers` (save; `type: "Ai"`, `when` = one of the four AI events, any action; omit `triggerId` to create), `GET /{version}/ai/triggers`, `GET /{version}/ai/triggers/{id}`, `PATCH /{version}/ai/triggers/{triggerId}/enable`, `PATCH /{version}/ai/triggers/{triggerId}/disable` and `DELETE /{version}/ai/triggers/{triggerId}`. The most complete walkthrough of the request — the polymorphic request, the action object and the per-channel delivery settings — is [Save Membership Trigger](/codemash/api-reference/membership/triggers/save-membership-trigger.md); the same structure applies to every source. ## What is different per module | Source | Extra fields on the trigger | Notes | | ---------- | -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Membership | — | `OnUserCreated` (a new person) is different from `OnRegistered` (a new login). The portal does not offer `OnUserCreated` yet; save it through the API. | | Database | `schemaId`, `configurationCode`, `env` | Defined per collection, from the collection's schema; `env` is the environment this copy of the trigger belongs to. An update also carries the previous values. | | Files | `folder` | The watched folder, subfolders included; empty = every file. | | Payments | `integrations`, `events` | Narrows the trigger to some payment integrations and some provider event names (for example `payment_intent.succeeded`); empty = all of them. | | AI | — | API only (see above). | ## Related * [Campaigns](/codemash/cloud/concepts/campaigns.md) — what the Email, SMS and Push actions start * [Message templates](/codemash/cloud/concepts/message-templates.md) — what those campaigns send * [Integrations](/codemash/cloud/concepts/integrations.md) — the provider an action sends through * [Webhooks](/codemash/cloud/project/settings/webhooks.md) — destinations for the webhook action