Automation Triggers

Configure event and schedule-based triggers for your automations

Triggers define when an automation runs. Alguna supports event triggers that respond to platform events and schedule triggers for time-based workflows.

Every automation has exactly one trigger.

---

Configuring Triggers

1. Navigate to Automations in the dashboard
2. Click Create Automation
3. In the trigger step, choose:
   • Event: run when a platform event occurs
   • Schedule: run at chosen times
4. Configure the trigger’s condition and execution policy
5. Add steps
6. Save, then activate the version

---

Event Triggers

Event triggers fire when something happens in your account. There are twelve event types.

Payments

Event type	Fires when
payment_failed	A payment attempt fails
card_expiring	A customer’s stored card enters its expiry month

Invoicing

Event type	Fires when
invoice_status_updated	An invoice status changes

Usage metering

Event type	Fires when
prepaid_usage_update	Prepaid usage is updated
credits_depleted	A customer’s credits balance is fully depleted

Quotes

Event type	Fires when
subscription_sent_for_signature	A subscription is sent for signature
quote_signed	Every signer has signed a quote and its signature session completes

Subscriptions

Event type	Fires when
subscription_status_updated	A subscription status changes
subscription_renewal_window_entered	A subscription’s contract end date falls within the renewal window
flow_session_completed	A hosted flow session is completed

CRM

Event type	Fires when
salesforce_opportunity_changed	A Salesforce opportunity is created or changed
hubspot_deal_changed	A HubSpot deal is created or changed

Automation event types are not webhook events. Webhook subscriptions use a separate catalogue (invoice.paid, subscription.activated, and so on) that cannot be used to trigger an automation, and the twelve types above cannot be subscribed to as webhooks.

---

Trigger Data

Each event carries a payload. The builder lists the available fields when you pick an event type, and offers them in the variable picker on every downstream input.

Event type	Key fields
payment_failed	paymentId, accountId, invoiceId, paymentMethodId, amount, currency, failureReason
card_expiring	accountId, paymentMethodId, cardBrand, cardLastFour, cardExpiryMonth, cardExpiryYear, isDefault
invoice_status_updated	invoiceId, accountId, status, externalReference
prepaid_usage_update	priceId, productId, productName, subscriptionVersionId, accountId, maxUsageBeforeOverages, currentUsage, usagePercentage
credits_depleted	customerId, creditType
subscription_sent_for_signature	customerId, subscriptionId, recipients, isReminder, recipientType
quote_signed	quoteID, subscriptionID, accountID
subscription_status_updated	subscriptionId, status
subscription_renewal_window_entered	subscriptionID, accountID, termEnd, daysUntilRenewal, renewalKey, currency, currentACV
flow_session_completed	flowSessionId, hostedFlowId, accountId
salesforce_opportunity_changed	provider, integrationID, recordID, recordURL, stage, stageEntered, changedFields
hubspot_deal_changed	provider, integrationID, recordID, recordURL, stage, stageEntered, changedFields

Reference a field from a step as {{trigger.inputs.<field>}}. Full field tables, including which fields are always present, are in the reference.

---

Narrowing Which Events Run

A trigger has no separate filter builder. Narrowing is done in two ways, both configured on the trigger itself.

Trigger condition

An optional condition, written as one or more expr expressions joined with AND or OR, evaluated against the event payload. Fields are referenced by bare name — no {{...}} wrapper.

Goal	Trigger	Condition
Only overdue invoices	invoice_status_updated	status == "overdue"
Only large failed payments	payment_failed	amount > 10000
Only at 80% of a commitment	prepaid_usage_update	usagePercentage >= 0.8
Only when a deal reaches Closed Won	salesforce_opportunity_changed	stageEntered && stage == "Closed Won"
Only failures tied to an invoice	payment_failed	invoiceId != nil

If the condition is not satisfied, no run starts. See Conditions.

Execution policy

Policy	Behavior
Execute every time (always)	Run whenever the trigger fires and its condition passes
Execute only once per unique value (once)	Run only the first time each value of a chosen event field is seen

With once you also choose the field to track. It can be a top-level field (invoiceId, accountId) or a dot path into a nested object (changedFields.Amount.after).

This is what keeps a dunning automation from re-prompting a customer on every retry of the same invoice: track invoiceId, and the customer is contacted on the first failure only.

Suppression is scoped to the automation, not the version, so editing an automation does not reset its history and re-fire values it already handled. prepaid_usage_update refines the slot further, scoping suppression to the commitment period and the prepaid price so the same customer can be alerted again in the next period.

---

Schedule Triggers

Schedule triggers run automations at chosen times rather than in response to an event.

Calendar schedules

The builder writes calendar schedules. Pick a frequency and a time:

Frequency	Description
Hourly	Every hour, at a chosen minute
Daily	Every day, at a chosen time
Weekly	On chosen days of the week, at a chosen time
Monthly	On chosen days of the month, at a chosen time
Yearly	In chosen months, on chosen days, at a chosen time

Underneath, a calendar schedule is a set of ranges over year, month, dayOfMonth, dayOfWeek, hour, minute and second, and it fires at each point matching all of them.

Interval schedules

A schedule can instead run on a fixed interval: an every duration, with an optional offset to shift its phase. Durations use the units seconds, minutes, hours, days, weeks, months, quarters, years.

Automations do not support cron expressions. A schedule is either a calendar or an interval; there is no cron field in the trigger model.

Schedule triggers can also carry a condition and an execution policy, though a scheduled run’s “event” carries no per-record fields to filter on — most scheduled automations start with a lookup action such as get_invoices and filter from its output instead.

---

Common Trigger Patterns

Dunning on first failure

1. Trigger: payment_failed
2. Condition: invoiceId != nil
3. Execution policy: once per invoiceId
4. Action: send_billing_info_request

Alert the team on a large failed payment

1. Trigger: payment_failed
2. Condition: amount > 10000
3. Action: send_slack_message

Chase overdue invoices on a schedule

1. Trigger: schedule, daily at 09:00
2. Action: get_invoices filtered to overdue
3. Action: send_invoice_reminders_bulk with the previous step’s invoices

Open the renewal early

1. Trigger: subscription_renewal_window_entered
2. Action: create_quote of kind renewal
3. Action: create_crm_record to open the linked renewal opportunity

Close the opportunity when the quote is signed

1. Trigger: quote_signed
2. Action: set_opportunity_stage addressed by quoteId

---

Best Practices

Add a Condition

Narrow the trigger so runs only start for events you actually care about.

Use Once-Per-Value

Track invoice or account IDs so a customer isn’t contacted on every repeat event.

Test First

Use the test run to check the trigger data your steps will receive.

Monitor Executions

Review execution history to confirm triggers fire as expected.

---

Viewing Trigger History

1. Navigate to Automations and open the automation
2. Open its execution history
3. Each run shows the triggering event’s data, the status, the timestamp, and every step that ran

---

Troubleshooting

Trigger not firing

1. Verify the automation has an active version
2. Check the event type matches what you expect — automation event types are not webhook events
3. Review the trigger condition; a field name that does not exist on the payload will never satisfy it
4. Check the execution policy: with once, a value that already ran is suppressed for good

Automation runs too often

1. Add or tighten the trigger condition
2. Switch the execution policy to once per unique value and pick the right field
3. Check whether more than one automation is listening for the same event

Schedule not running

1. Confirm the automation has an active version
2. Re-check the calendar fields — a schedule with no matching day or month never fires

---

Next Steps

Actions

Learn about automation actions.

Conditions

Add conditional logic.

Reference

Full event payloads and schedule shapes.