Trigger catalog

Canonical list of Workflow Foundation triggers. How-tos stay short and link here. Screen guides do not copy this table.

In the builder, a trigger is three fields on the Build bar:

1. Trigger — what kind of event can start a run.
2. Where it happens — how wide that event is allowed to be (entire app, one screen, one button, one data source, and so on).
3. Target — the exact screen, button, sheet, or record. Entire-app workflows leave Target blank.

Use the narrowest trigger that matches the real event. Prefer Form or screen submitted over Record updated when the app form is the source of truth — edits made only in Notion do not look like a form submit.

What this is / when to use it

A trigger starts a workflow run. Type enum: WorkflowTriggerType. You attach it to a form, button, screen, data source, record, or the application (WorkflowAttachmentTargetType).

Before you start

Workflow entitlement is on. The target form, button, or sheet exists. You have read Which automation.

Build it

1. Open Automation → Workflows (or the wizard, which picks a trigger for you).
2. Set Trigger to one type below.
3. Set Where it happens, then bind Target when the scope is not Entire app.
4. Add conditions if the run should skip some events.
5. Add steps from the step catalog.
6. Save, publish the workflow, and publish the app.

Every control

Trigger	Enum	Typical Where it happens	Typical Target	Fires when	Do not use when
Form or screen submitted	form_submitted	Screen	The screen that owns the form	A create/update/delete save on that screen succeeds	You need Notion-only edits
Button or screen action	button_clicked	Button	The specific button	The user taps that control	You meant a URL button (OPEN_URL) that is not bound here
Manual start	manual_start	Entire app	Leave blank	Someone starts it from Launcher, Test workflow, or Simulate	Unattended intake from a form or webhook
Record created	record_created	Data source	The connected sheet/database	A new page appears in that source	You only care about the app form
Record updated	record_updated	Data source	The connected sheet/database	A watched page in that source changes	High-churn properties (you will over-fire)
Status changed	status_changed	Data source	The sheet that owns the status field	Status/select moves (optionally to a named value)	You need any field change — use Record updated
Scheduled	scheduled	Entire app	Leave blank	The schedule fires	Immediate reaction to a submit
Webhook received	webhook_received	Entire app	Leave blank	HTTP intake is accepted	You do not have a sender. See webhooks
Message received	message_received	Entire app	Leave blank unless you are scoping a contract	An inbound message matches channel/topic (and contract if set)	You do not have Messaging entitlement

Shared trigger fields: target_type (Where it happens), target_id (Target), conditions, config (for example To status, schedule, webhook intake).

---

Each trigger, Where it happens, and Target

The labels below are the ones on Build. Hidden/internal screens can appear in Target because workflows can send people there on purpose.

Form or screen submitted

Trigger: Form or screen submitted (form_submitted)

This is the usual trigger when a person in the published app fills a create or update form and saves. It fires inside the app, after that save succeeds. It does not fire when someone edits the same Notion database in Notion and never opens your app.

Where it happens

• Screen — use this almost always. The workflow listens only to form saves on one screen.
• Entire app — any form save in this app can start the run. Use this only when you truly want every form.
• Form — reserved for a form-specific id. Today’s app form saves are matched through the screen that owns the form, so choose Screen instead.

Target

Search for the screen that contains the form (for example Client Intake or Assign Job). The builder saves the screen id. Do not pick a different list or details screen that happens to use the same database.

Example: Client submits intake → Where it happens = Screen → Target = Client Intake.

Do not use if the work should start when a row is created in Notion by a person or another integration. Use Record created for that.

Button or screen action

Trigger: Button or screen action (button_clicked)

This fires when an end user clicks a workflow-aware button or completes a screen action the builder attached to the workflow. A normal Open URL button does not start a run unless you bind this trigger to that control.

Where it happens

• Button — use this when only one control should start the workflow (Approve, Reject, Mark reviewed).
• Screen — use this when several buttons or screen actions on the same screen should share one workflow. Button-click events include the current screen id, so a screen-scoped workflow can see them.

Target

• If Where it happens is Button, search by the button label (and the screen it lives on). The builder saves the control id.
• If Where it happens is Screen, search for that screen. Every matching action on that screen can start the run.

Example: Reviewer clicks Mark reviewed → Where it happens = Button → Target = Mark reviewed on the review screen.

Do not use for “when they submit the form.” That is Form or screen submitted.

Manual start

Trigger: Manual start (manual_start)

This does not watch the app. A person or a controlled test starts it on purpose: Automation Launcher Target workflow, Test workflow on Activity, or Simulate.

Where it happens

Entire app. There is no form or sheet to listen to.

Target

Leave Target blank. Entire-app workflows do not need a target. Publishing a scoped target here does not make the workflow start from a form.

Do not use for unattended intake (form, Notion row, webhook). Those need a real event trigger.

Record created

Trigger: Record created (record_created)

This fires when a new page appears in a connected Notion source (app sheet / database), whether it was created in the app or in Notion, depending on what that source is watching.

Where it happens

Data source — listen to one connected sheet or database. Entire app is too wide for most production apps.

Target

Search by the data source name (the connected Notion database or sheet). The builder saves the source id. Pick the database that receives the new row, not a related child database unless that is truly what should start the run.

Example: A new Job page appears in Jobs → Where it happens = Data source → Target = Jobs.

Do not use if you only care that someone submitted your form. Two workflows (form submitted + record created) on the same write will double-run.

Record updated

Trigger: Record updated (record_updated)

This fires when a watched page in the connected source changes — any property Notion reports as an update, from the app or from Notion.

Where it happens

Data source — one sheet/database.

Target

The same data source picker as Record created. Choose the database whose edits should start work.

Warning: If a later step writes the same sheet, this trigger can loop. Add a condition, or use Status changed so only one field matters.

Do not use for high-churn properties (last edited, counters, sync timestamps). You will over-fire.

Status changed

Trigger: Status changed (status_changed)

This is a narrower record trigger. It fires when a status or select field moves, not when every property on the page changes.

Where it happens

Data source — the sheet that owns that status field.

Target

Pick that data source. Then fill To status when you only want one destination value (for example With Client or Approved). Leave To status blank only if any status move should run the workflow.

Example: Job status becomes Assigned → Where it happens = Data source → Target = Jobs → To status = Assigned.

Do not use if you need “any field on the row changed.” That is Record updated.

Scheduled

Trigger: Scheduled (scheduled)

This starts from a clock (cron or interval), not from a user click. There is no form submit and no Notion event.

Where it happens

Entire app. The schedule belongs to the workflow, not to a screen.

Target

Leave blank.

Do not use when the next step should happen the moment someone submits. Use Form or screen submitted (and a Wait step if you need a delay after that submit).

Scheduled workflows need the matching entitlement. They are for reminders, nightly sweeps, and overdue checks.

Webhook received

Trigger: Webhook received (webhook_received)

This starts when an external service POSTs JSON to this app’s workflow intake and the request is accepted. Generate a secret in External webhook intake and send it as x-notionapps-webhook-token (Bearer and x-workflow-webhook-token also work).

Where it happens

Entire app. Intake is per app, not per screen.

Target

Leave blank. The sender is Make, Zapier, or another HTTP client, not a builder picker object.

Copy the intake URL and token from the builder. After this app has an active secret, the old shared platform token stops working for it. Admins can inspect attempts in Admin → Workflow Operations → Webhooks → Inbound.

Do not use if you only need to send email. Use a Notify step on a form or button trigger.

Details: Webhook Technical Reference, Workflow vs Messaging Webhooks.

Message received

Trigger: Message received (message_received)

This starts when Application Messaging routes a matching channel, topic, and optional contract into the workflow. External systems can POST JSON to the messaging intake URL with the same per-app token. This is not SMS and not the Notify email step.

Where it happens

Usually Entire app. The match is the messaging route, not a form screen.

Target

Leave blank unless you are deliberately scoping to a contract or related object the picker exposes. Messaging entitlement must be on.

Do not use if the event is “user submitted a form in this app.” Use Form or screen submitted, then a Publish message step if you also need the bus.

Topic names: Topics that perform work.

---

What users see

Nothing at the trigger. They see later steps: a notification, a queue item, a status change, or a confirmation on the screen.

Limits and plans

• Scheduled and webhook need entitlements and, for webhook, an external token. Makers copy the intake URL from the workflow builder; they do not handle ops env files.
• record_updated can loop if a step writes the same sheet. Add a condition or use status_changed.
• Simulate / test runs are for makers. They still create runtime items unless the tool says otherwise.

Example

Inspection Assign Job form → form_submitted → Where it happens = Screen → Target = Assign Job screen → create_related_records photo slots → send_notification to the inspector. Do not also use record_updated on the same form’s writes.

Fix problems

Symptom	Likely cause	What to do
Submit does not start a run	Trigger bound to the wrong screen, or draft not published	Confirm Where it happens = Screen and Target is the form screen. Publish workflow and app.
Button does nothing	URL button, or Target is a different control	Bind Button or screen action to that control. Open URL alone does not start a run.
Double runs	Two triggers on the same save	Remove form submitted or record created/updated, not both.
Webhook 401	Token / URL mix-up	Webhook reference.

Related

Step catalog. Start From a Wizard. Workflow Foundation User Guide. Workflow How-To Guide.