Triggers

In GTM Engine, triggers are standalone entities — not properties of a workflow. One trigger can fan out to many workflows and/or campaigns; one workflow can be invoked by many triggers. The relationship is many-to-many via trigger_workflows (workflows) and trigger_campaigns (campaign auto-enrollment).

Triggers live in the unified Automation Library alongside workflows and agents. They support tags and folder tags so a single use case (e.g. folder:Onboarding) groups its triggers, workflows, and agents together.

Trigger types

Common types include:

• RecordCreated — fires when a record (account, contact, opportunity, etc.) is created.
• RecordUpdated — fires when a record changes, with filters on which field changed and to what value (e.g. stage_id moved to a specific stage). Filters are env-specific (stage names, enum values), so the install flow flags them as editable when copying a system trigger into your org.
• ActivityCreated — fires when an activity (email, meeting, transcript, etc.) is logged.
• OpportunityAssociated (Open Opportunity) — fires for the contacts associated with an opportunity when it's created or updated, with an optional filter to fire only while the opportunity is in an open stage (not won or lost). Primarily used for campaign auto-enrollment.
• Timer / Schedule — cron-style scheduled runs. Created via the same scheduler-sync path whether you build the trigger by hand or have Genie create it.
• Webhook — invoked by an external system POSTing JSON to a per-trigger URL. See Webhook triggers below.

Webhook triggers

A webhook trigger gives you a unique inbound endpoint that external systems can POST JSON to, letting events that happen outside GTM Engine (form submissions, sign-ups, product events, and so on) kick off your workflows.

When you create a webhook trigger you get an endpoint URL of the form:

{API_BASE_URL}/webhooks/trigger/{triggerId}

External systems send an HTTP POST with a JSON body to that URL. Each delivery is stored, and the trigger's Recent deliveries panel shows the most recent payloads. For the full request/response contract (headers, body limits, status codes, and code examples), see the Webhook ingestion API reference.

Securing the endpoint

Every webhook trigger requires a secret — there is no open/unauthenticated mode. Each trigger has an Authentication setting with two options:

• Shared webhook key — the request must include the specific org-level webhook key selected on that trigger in the X-Webhook-Secret header. You create webhook keys on the API Keys page (/automation/api) with the Webhook permission, then select one while configuring the trigger. The same key can be selected for as many webhook triggers as you like — ideal when a single marketing site fires many different events — but other webhook keys in the org cannot invoke those triggers. The key is shown once when created (copy it then); disable or replace it from the API Keys page.
• Unique secret for this trigger — a dedicated secret is generated that only this trigger accepts, also sent in the X-Webhook-Secret header. The secret is shown once when it's created — copy it then, because it's stored only as a hash and can't be retrieved later. If you lose it, rotate the trigger to generate a new one.

Requests that don't present the required key/secret are rejected with 401.

Using the payload as variables

Delivered payloads are flattened into dot-notation fields (for example payload.user.email, payload.form.company), which appear as mappable variables in the trigger-to-workflow mapping editor. The fields offered are discovered from recent deliveries, so send a test payload first to populate them.

If you'd rather pass the whole body through, enable Expose the entire body as a variable and use the one-click Map entire body option to map a workflow input to the payload root — the workflow then receives the full JSON body.

Fanning out to campaigns

The same triggers that drive workflows can also drive campaign auto-enrollment. Linking a trigger to a campaign (from the Live Campaign builder's Enrollment triggers section or campaign settings) enrolls the resolved contacts when the trigger fires. These links surface on the Process Map as a distinct campaign automation node — separate from Workflows and Agents. See Auto-Enroll Contacts into a Live Campaign.

Inputs: explicit trigger-to-workflow variable mapping

The old implicit {{trigger.*}} namespace is replaced by explicit mapping from trigger output → workflow input variable. When you assign a trigger to a workflow, you map each trigger output (e.g. record_id, previous_stage_id, current_stage_id) onto a named workflow input variable. This makes the contract between trigger and workflow visible and validates at edit time.

When a workflow is installed from the Automation Library Explore tab and has linked trigger templates, the install modal:

1. Detects the triggers.
2. Shows a review step.
3. Flags env-specific RecordUpdated filter values (stage names, enum values) as amber-highlighted editable fields before copying them in the same transaction as the workflow.

Where triggers are managed

• Editing triggers and the Process Map — the top-level Automation Library workspace.
• Per-workflow trigger list — the Triggers / Inputs / Outputs panel on the workflow canvas shows which triggers are wired to that workflow and their variable mappings.
• Genie — Workflow Builder Genie can search existing triggers, create new ones, install recommended trigger templates, assign triggers to workflows, and update trigger-to-workflow variable mappings.

Next steps

• Workflows — how a triggered workflow is built.
• Variables — how trigger outputs flow into workflow inputs.