> ## Documentation Index
> Fetch the complete documentation index at: https://learn.workflow.dog/llms.txt
> Use this file to discover all available pages before exploring further.

# External triggers

> Configure and operate provider-backed event subscriptions safely.

An **external trigger** listens for events from another service, such as a new
Gmail message, a Google Forms response, a Microsoft Outlook message, or a
TidyCal booking.

The trigger's account and settings describe the event source. When the
provider sends an event, WorkflowDog converts it into one or more workflow runs.

## Configure an external trigger

<Steps>
  <Step title="Choose the trigger">
    Create a workflow and choose the provider event that should start it.
  </Step>

  <Step title="Connect an account">
    Open **Configure Trigger**, select a healthy integration account, and approve
    any required permissions.
  </Step>

  <Step title="Set the event filters">
    Choose the mailbox, label, form, or other trigger-specific source. See that
    trigger's reference page for its exact fields.
  </Step>

  <Step title="Save and verify the source">
    Wait for the trigger configuration to finish updating. WorkflowDog creates or
    adopts the required provider subscription during configuration.
  </Step>

  <Step title="Enable and test">
    Set the workflow Live, send a new provider event, and inspect the resulting
    run.
  </Step>
</Steps>

<Note>
  External event sources are configured even while the workflow is Paused. Live
  or Paused controls run eligibility; it is not the switch that creates or
  removes the provider subscription.
</Note>

## How subscriptions are reused

WorkflowDog creates a deterministic identity for each logical event source. If
multiple workflows need the same underlying source, they can share one
provider subscription instead of creating duplicates.

For example, two workflows can listen to different event types delivered by
the same account-backed provider subscription. WorkflowDog tracks which
workflow and trigger type should receive each event.

This sharing affects cleanup:

* Changing one workflow removes only the source relationship it no longer
  needs.
* If another workflow still uses the source, the provider subscription stays
  active.
* If no workflow uses it, WorkflowDog cleans up the external resource and
  deletes the source.

## Change trigger configuration

Saving a new trigger configuration performs a reconciliation:

1. WorkflowDog derives the event sources required by the new settings.
2. It creates or adopts those sources.
3. It removes obsolete relationships from the workflow.
4. It tears down an obsolete provider subscription only when nothing else uses
   it.

This is why account and source changes should be made through **Configure
Trigger** instead of by editing raw workflow data.

After a material change, send a new event that matches the new configuration.
Changing the source does not replay events that occurred under the old
configuration.

## Pause without removing the subscription

When a workflow is Paused, external subscriptions continue receiving events.
Each attempted run is recorded as Failed with **The workflow is paused** and is
not queued for later.

Use Paused for temporary execution control. If you need the provider
subscription itself removed, change the trigger configuration, disconnect the
account, or delete the workflow.

Read [Enable and pause workflows](/essentials/enable-and-pause) for scheduled
run behavior and other pause caveats.

## Reconnect an account-backed trigger

Provider credentials can expire, be revoked, or lose permissions. WorkflowDog
marks an account unhealthy when it can no longer use it and notifies Editors
of projects linked to that account.

Reconnecting updates the credentials and starts best-effort background recovery
for account-backed event sources. A source that needs fresh setup is torn down
and recreated while preserving the workflows and event types that used it.

<Warning>
  Recovery is asynchronous and is not a guarantee that events missed during an
  account or provider outage will be replayed. After reconnecting, verify the
  trigger and send a new event.
</Warning>

If a provider renewal worker exhausts its retries, the event source is marked
unhealthy. A later setup or account-recovery cycle can rebuild it from scratch.

## Disconnect an account

Disconnecting an account from a project clears matching account values from
trigger configurations. WorkflowDog processes those trigger updates normally,
so obsolete event-source links and unused provider subscriptions are cleaned
up.

Before disconnecting:

1. Connect the replacement account.
2. Pause workflows that can cause side effects.
3. Reconfigure every trigger that uses the old account.
4. Send a test event through the replacement.
5. Disconnect the old account.

The Integrations page's **Swap Accounts** tool does not update trigger
configurations. See [Integrations](/essentials/integrations).

## Delete workflows and projects

Deleting a workflow removes its event-source relationships. Shared sources stay
active for other workflows; unshared sources are cleaned up.

Deleting a project cleans up event sources for its workflows before the project
and its data are deleted.

## Operate triggers reliably

* Use a dedicated service account when employee access may change.
* Grant every permission required by the trigger, not only by its downstream
  actions.
* Treat a **Needs Reconnecting** badge as an operational incident.
* Send a new test event after changing an account or event filter.
* Inspect run history for Paused, billing, or node errors before assuming the
  provider subscription is broken.
* Do not rely on automatic backfill unless the individual trigger reference
  explicitly documents it.

## Troubleshooting

<AccordionGroup>
  <Accordion title="The provider event happened but no successful run appeared">
    Confirm the workflow is Live, then inspect history for a Paused or billing
    failure. Check the integration account for **Needs Reconnecting**, review
    the trigger filters, and send a new event after correcting the issue.
  </Accordion>

  <Accordion title="Pausing did not stop provider deliveries">
    This is expected. Pausing rejects new runs but keeps the provider subscription
    configured. Reconfigure or disconnect the trigger source when you need the
    external subscription removed.
  </Accordion>

  <Accordion title="Disconnecting one workflow affected another">
    Accounts are project resources, and disconnecting an account clears its
    references across the project. Reconfigure affected workflows with a
    replacement account before disconnecting.
  </Accordion>

  <Accordion title="The account is healthy but the trigger still does not fire">
    Open and save the trigger configuration to run source reconciliation, then
    send a new matching event. Also verify provider-side filters and
    permissions. If the issue continues, reconnect the account.
  </Accordion>
</AccordionGroup>