Triggers
| Trigger | When it fires |
|---|---|
submission.created |
A clean submission lands (post-spam-scan). |
submission.updated |
A submission's payload or tags change. |
submission.tagged |
A tag is added (manual or automated). |
submission.marked_spam |
A submission moves to spam. |
submission.starred |
A user stars a submission. |
manual |
"Run now" or API /run. |
schedule.cron |
Cron expression in trigger_config.cron. |
webhook.failed |
A webhook delivery exhausts retries. |
Choosing a trigger
Use submission.created for the most common workflow: a clean row arrives and the team needs to notify someone, tag it, sync it, or classify it. Use the status and tag triggers when the workflow should react to triage work that happens after intake.
Manual triggers are useful for backfills and one-off tests. A manual run can be started from the dashboard or the API, and it creates the same run records as event-driven triggers.
Scheduled triggers use trigger_config.cron. Keep scheduled workflows idempotent because they are not tied to a single respondent action. For example, a scheduled digest should query the current state and send one report, not blindly repeat work for every historical submission.
Debugging triggers
If no run appears, confirm the automation is active, the trigger type matches the event, and the form or survey that emitted the event owns the automation. For quota-limited teams, the dispatcher can skip new runs after the monthly run limit is reached.