--- title: "Triggers: What Starts an Automation" description: "Run by hand, on a schedule, on a webhook, on a BankSync event, when a table row changes, from a dashboard button, or when a bank poll finds something; with the guarantees, filters and sample data of each." section: "Automations" canonical: "https://banksync.io/docs/automations/automations-triggers" specs: ["automations"] operationBindings: [{"capability":"automations","operation":"automations.nodes.search"},{"capability":"automations","operation":"automations.nodes.describe"},{"capability":"automations","operation":"automations.nodes.options"},{"capability":"automations","operation":"automations.activate"},{"capability":"automations","operation":"automations.deactivate"},{"capability":"automations","operation":"automations.webhooks.rotate"}] --- A trigger is the first card of an automation: it says when a run starts and what the first step is handed. An automation can have several triggers, and each can be tested with its own sample data. The library's **Starts when** group lists every trigger your workspace offers. ## Run by hand Starts when a person presses **Run now** in the toolbar, or an API key or agent starts the automation. What the first step is handed is whatever the caller supplied. Use it for automations people start on demand, and as a second trigger on any automation you want to be able to start yourself. ## On a schedule Starts on a timetable in the automation's time zone: **every few minutes**, **every hour**, **every day**, **every week** (on the days you pick) or **every month**, or a cron expression you write. A schedule that would fire while the previous run is still going is handled the way you choose in the trigger's settings (overlap). Daylight-saving changes are handled for you: the next firing is worked out in the time zone, not in UTC. An automation that must not miss something — a feed that failed overnight, say — is best built on a schedule that reads the facts, rather than on an event alone. ## On a webhook Starts when a request reaches the automation's own secret link. The link is shown **once**, when you turn the automation on; **Get a new webhook address** replaces it and stops the old one at once. Anything from outside can send to the link, so what it sends is untrusted: a step that cannot be undone will not take its target from it, and a step that cannot be undone downstream of an unverified webhook needs an approval step first. To accept only requests a service really sent, give the trigger a signing secret. See [Webhooks](/docs/automations/automations-webhooks) and [Webhook signing secrets](/docs/automations/webhook-signing-secrets). ## When something happens in BankSync These start when BankSync records an event. An event carries ids, kinds, counts and times, never a credential, an amount of money or free text, so add a step that reads the details you need (a bank's balance, a feed's last run, a case's status). | Where | Triggers | | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Banks | When a bank is connected · needs signing in again · works again after signing in · disconnects · is removed · when a bank consent is about to expire | | Feeds | After a feed runs · When a feed fails · When a feed is paused after failing · When an enrichment is applied · When a delivery fails · When a document is read | | Mailboxes | When mail reaches a mailbox · When a mailbox holds mail · When mail a mailbox sent is delivered or bounces | | Billing | When the workspace subscribes · When the plan changes · When the subscription is cancelled · When a payment fails · When a failed payment recovers | | Forms | When a form is submitted | | Clients | When a client connects a bank | | Support | When a support case is opened · When support replies · When someone replies on a case · When a case changes status · When a case misses its response time · When a snoozed case wakes · When a support email bounces | **How sure is it?** Bank, feed, mailbox, billing, client and support events are **best-effort**: the fact is recorded just after it happens, so a run can start a little late and, rarely, not at all. A form submission is recorded with the submission itself. Support events are relayed from BankSync support, usually within a minute, and never carry a word of the case. **Narrowing it.** A bank or feed trigger can watch one bank or feed (picked, or bound) or all of them. Mail triggers can filter by sender, address, subject, whether there is an attachment and whether the sender was authenticated. Every event trigger also has **Only when**, an expression over the event (`item`) that must be true for a run to start, for example `item.data.reason = "consent_expired"`. **Not twice.** An event the automation itself caused starts nothing, and an event delivered twice starts one run. In a workspace that restricts access, an event about a bank, feed, mailbox, client or table starts a run only when the member who approved the automation can see that item. ## When a table changes Offered on a table (its **Automate** menu) and in the library where your workspace has tables: - **When a row is added**, **when a row changes** (any field, or a status moving to the option you pick), **when a row is moved to the trash**, **when a row comes back from the trash**. - **When a row starts to fit a view's filter** — the row entered the view you chose. - **When a sync or import adds many rows at once** — one run for the batch, not one per row. - **When a file is attached to a row.** - **Conversations on a row**: when a message is added (by a side, on a channel, the first one, and so on), when the conversation is closed or reopened, when a message sent on it bounces, when somebody new is put on it, when it begins. Table triggers are recorded with the row write itself, so they never go missing. Starting an automation on a date held in a row is not offered yet: the template that would need it is shown greyed with that reason. ## When a bank poll finds something Four triggers watch one account of a bank, from the bank's page or the library: | Trigger | When it starts a run | | ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | When a transaction arrives | Once for each new transaction. Transactions already there when the automation is turned on do not start it; pending ones only if you ask. | | When a balance crosses a level | Once each time the balance goes below (or above) the amount, and at once if it already is when turned on. | | When an expected payment has not arrived | Once for each gap: no transaction with the words you give (a payer's name, say) within the days you set. | | When holdings or trades change | Once for each new trade of an investment account, or each time its holdings change (a position bought, sold or resized). What is there when it is turned on starts nothing. | They are checked no more often than your plan syncs a feed, from what BankSync has already read from the bank: they never ask the bank to refresh, and while the bank is asking BankSync to wait, they wait too. A check that finds nothing starts nothing. They ask for `banks:read`, like the reading steps. ## From a dashboard button Starts when a person presses an action button on a dashboard that names this automation and this trigger. The first step is handed the dashboard, the widget the button is on and the row selected in it. Only a person who may start runs sees the button, and only while the automation's grant is active. The row is the dashboard's data, so it is untrusted like any other content. ## Called by another automation A **Call an automation** step in one automation starts another, with an input, and can wait for its answer. The called automation must list the caller among the automations that may call it. See [Branches, loops, parallel paths and failures](/docs/automations/automations-control-flow#calling-another-automation). ## Sample data for a trigger Every trigger carries a sample of what it hands on, used by **Test** and **Test this step**. **More → Settings → Test data** lets you replace it with your own JSON, as `{ "outputs": { "main": … } }`, or `{ "error": … }` to rehearse a failure. See [Testing, running and run history](/docs/automations/automations-testing-and-runs). ## Turning triggers on and off The toolbar's **On/Off** switch turns every trigger of the automation on or off at once. Turning it off lets runs already going finish. Moving an automation to the trash turns its triggers off too; restoring it leaves it off until you turn it on again. An automation whose bank was removed or whose feed was deleted is turned off and marked paused, with what went away.