Sources
A source is a trigger - something that fires events the rules engine can act on. When you build a rule, the first thing you choose is its source. Each source hands your payload a context: a set of variables describing what just happened, which you can drop into a card or raw body.
This page covers the built-in sources. To trigger on anything else Craft or a plugin does, see Custom events. To add your own source from a module or plugin, see For developers.
The built-in sources at a glance
| Source | Fires when… | Trigger type |
|---|---|---|
| Custom event | Any class + event you name (e.g. craft\elements\Entry / afterSave) | Instant |
| Entry saved | An entry is created or updated (drafts and revisions skipped) | Instant |
| User event | A user registers, is activated, or changes group | Instant |
| Integration failure | A queued job fails after Craft's retries, or your code reports one | Instant |
| Freeform submission | A Freeform form is submitted (needs Freeform) | Instant |
| Queue size | A scheduled check finds the queue over a threshold | Scheduled |
You don't have to memorise the tables
Every source lists its own variables right in the rule editor, so you don't need to keep this page open while you build. The tables below are for reference.
Entry saved
Fires when an entry is created or updated. Drafts and revisions are ignored, so you're notified about real, saved content and not every autosave.
Add a condition like section equals news to target a section, or isNew equals true to notify only on first publish.
Condition fields and card variables:
| Variable | What it is |
|---|---|
{section} | Section handle |
{type} | Entry type handle |
{title} | Title |
{url} | Public URL |
{cpEditUrl} | Control panel edit URL |
{authorName} | Author name |
{status} | Status |
{isNew} | Whether the entry was newly created |
The full entry element is also available to the payload as {{ entry }}, so you can reach any field on it, e.g. {{ entry.myCustomField }}.
User event
Fires on user lifecycle events: registration, activation, and group changes. The event field tells you which happened - it's one of registered, activated, or groupChanged - so a condition like event equals registered targets just one.
| Variable | What it is |
|---|---|
{event} | Which happened: registered, activated, or groupChanged |
{email} | |
{username} | Username |
{fullName} | Full name |
{groups} | The user's group handles |
The full user element is available to the payload as {{ user }}.
Integration failure
Fires when a background (queue) job fails after Craft has exhausted its retries - a sync job, a mailer send, or any plugin's queue job. It also fires when your own code reports a failure through the plugin's API (see For developers).
This is the one to reach for when you want to know the moment something breaks behind the scenes, rather than finding out from the queue screen later.
| Variable | What it is |
|---|---|
{title} | A short title for the failure |
{detail} | The detail or error message |
{jobClass} | The failed job's class |
{jobDescription} | The job's description, if it has one |
{attempt} | Which attempt failed |
{error} | The error message |
The plugin's own delivery jobs are deliberately excluded, so a failed webhook send can never trigger a "job failed" notification about itself.
Freeform submission
Fires when a Solspace Freeform form is submitted. This source only appears when Freeform (5.x) is installed and enabled.
Filter by formHandle or formId to target a specific form.
| Variable | What it is |
|---|---|
{formHandle} | Form handle |
{formName} | Form name |
{formId} | Form ID |
{submissionId} | Submission ID |
{fields.<handle>} | A single submitted field value, by its handle, e.g. {fields.email} |
{allFields} | Every submitted field, formatted as a labelled list |
{submissionUrl} | A control-panel link to the submission |
{fields.<handle>} and {allFields} read every field across all pages of a multi-page form, and skip HTML blocks and submit buttons. {allFields} is the quickest way to forward a whole submission without listing each field by hand.
Custom event
The general-purpose trigger: fire a rule on any Yii or Craft event you name. It's powerful enough to have its own page - see Custom events.
| Variable | What it is |
|---|---|
{{ event }} | The event object, e.g. {{ event.sender.title }} |
{{ sender }} | A shortcut for the event's sender |
Queue size (scheduled)
Unlike the others, this source doesn't react to an event - "the queue is too big" isn't something Craft fires an event for. Instead you run a console command on a schedule, and each run checks the current queue size and dispatches it to this source's rules.
Add it to cron:
php craft webhook-notifier/monitor/queue # e.g. every 15 minutes
php craft webhook-notifier/monitor/queue --cooldown=30 # at most one alert / 30 minThen pair it with a numeric condition such as total is greater than 50.
| Variable | What it is |
|---|---|
{total} | Total jobs in the queue |
{hasWaiting} | Whether there are waiting jobs (true/false) |
{hasReserved} | Whether there are reserved jobs (true/false) |
How often you're alerted is set by how often the cron runs while the queue stays over the threshold. The optional --cooldown (in minutes) throttles repeat alerts so a persistent backlog doesn't message you every single run.