Trigger a workflow with events or Pub/Sub messages

You can use an Eventarc trigger to execute a workflow as a result of an event or a set of events. The events are routed from an event provider to interested event receivers.

Eventarc delivers events to the event receiver in the CloudEvents format through an HTTP request. The Workflows service converts the event to a JSON object (following the CloudEvents specification) and passes the event into the workflow execution as a workflow runtime argument.

An execution of your workflow is triggered:

  • When an audit log is created that matches the trigger's filter criteria. For example, see this quickstart in which you trigger Workflows with events from BigQuery using Cloud Audit Logs.
  • In response to direct events such as an update to a Cloud Storage bucket or an update to a Firebase Remote Config template. For example, see this quickstart in which you trigger Workflows with direct events from Cloud Storage.
  • By messages published to a Pub/Sub topic. For example, see this quickstart in which you trigger Workflows with Pub/Sub messages.

Note the following:

  • Events are considered delivered as soon as the workflow execution starts, and the actual execution takes place asynchronously in the Workflows services.

  • Executions triggered by events are not retried if the workflow execution starts, but later fails. For more information, see the Event retry policy.

  • When using Workflows as the destination for an Eventarc trigger, events larger than the maximum Workflows argument size will fail to trigger workflow executions. For more information, see Quotas and Limits.

Create a trigger using the Google Cloud CLI

You can create a trigger by running a gcloud eventarc triggers create command along with required and optional flags. For more information, see Create a trigger for Workflows.

Create a trigger using the console

The following steps show you how to create a trigger on the Workflows page in the Google Cloud console.

Before you begin

  1. Enable the Eventarc and Pub/Sub APIs.

    Enable the APIs

  2. Create a service account so that Eventarc can make requests to the Workflows API:

    1. In the console, go to the Service Accounts page.
      Go to Service Accounts

    2. Select a project and then click Create service account.

    3. In the Service account name field, enter a name that is between 6 and 30 characters.

      It can contain lowercase alphanumeric characters and dashes. After you create a service account, you cannot change its name.

    4. Click Create and continue.

    5. Grant your new service account the workflows.invoker role so that the account has permission to trigger your workflow. In the Select a role list, select Workflows > Workflows Invoker.

      If you are developing a production app, always grant the least permissive roles possible. For more information, see Manage access to projects, folders, and organizations.

    6. Click Done.

  3. To allow the principal that will run your Eventarc commands the ability to act as an Identity and Access Management (IAM) service account, grant a role that allows the principal to impersonate the service account.

Configure the trigger

  1. If you do not already have a workflow that you want to trigger, create and deploy one.

  2. In the console, go to the Workflows page:
    Go to Workflows

  3. On the Workflows page, select a workflow to go to its details page.

  4. On the Workflow Details page, click Edit.

  5. On the Edit Workflow page, select Add new trigger > Eventarc.

    The Eventarc trigger pane opens.

  6. Type a Trigger name.

    This is the ID of the trigger and it must start with a letter. It can contain up to 63 lowercase letters, numbers, or hyphens.

  7. Select an Event provider.

    This is the Google or partner service that is the source of events. For example, select BigQuery.

  8. Select an Event.

    • Custom events—Applies to a Cloud Pub/Sub event provider
    • Direct events—Applies to some event providers only
    • via Cloud Audit Logs events—Applies to all event providers

    Custom

    Requests to your service are triggered when a message is published to a Pub/Sub topic. This applies to a Cloud Pub/Sub event provider.

    1. From the events listed under Custom, select Cloud Pub/Sub topic.

    2. Select an existing topic or accept the default of None so that a new topic is created for the trigger.

      The existing Pub/Sub topic must be in the same project as the trigger.

      By default, Pub/Sub subscriptions created for Eventarc persist regardless of activity and do not expire. To change the inactivity duration, see Manage subscriptions.

      As a best practice, we recommend not to reuse the Pub/Sub topic created by a trigger because deleting an Eventarc trigger also deletes any Pub/Sub topics that were created by the trigger.

    3. Select a Region.

      Pub/Sub triggers for Eventarc are only available in single-region locations, and you cannot create a global Eventarc trigger.

    Direct

    Cloud Storage

    Requests to your service are triggered in response to an event inside a Cloud Storage bucket—object creation, deletion, archiving, and metadata updates. This applies to a Cloud Storage event provider.

    1. From the events listed under Direct, select one of the following:

      • google.cloud.storage.object.v1.archived: Event is sent when a live version of an object is archived or deleted. This event is only sent for versioning buckets.
      • google.cloud.storage.object.v1.delete: Event is sent when an object is permanently deleted. Depending on the object versioning setting for a bucket this means:
        • For versioning buckets, this is only sent when a version is permanently deleted (but not when an object is archived).
        • For non-versioning buckets, this is sent when an object is deleted or overwritten.
      • google.cloud.storage.object.v1.finalized: Event is sent when a new object is created (or an existing object is overwritten, and a new generation of that object is created) in the bucket
      • google.cloud.storage.object.v1.metadataUpdated: Event is sent when the metadata of an existing object changes.
    2. Specify or browse for the globally unique identifier of the Cloud Storage Bucket.

      The Cloud Storage bucket must reside in the same Google Cloud project and region or multi-region as the Eventarc trigger.

    3. Select a Region.

      Cloud Storage triggers for Eventarc are available in single-region, dual-region, and multi-region locations. Note that the Cloud Storage bucket must reside in the same Google Cloud project and region or multi-region as the Eventarc trigger.

    Events are delivered using Pub/Sub notifications from Cloud Storage. Setting up too many notifications registered against the same bucket might exhaust the notification limit for the bucket as indicated by the error Cloud Storage bucket ...: Pub/Sub notification limit reached. The bucket can have up to 10 notification configurations set to trigger for a specific event. See more quotas and limitations in the Cloud Storage quotas and limits page.

    Firebase Alerts

    Requests to your service are triggered in response to an event when a Firebase alert is published by a Firebase service.

    1. From the events listed under Direct, select google.firebase.firebasealerts.alerts.v1.published.

    2. In the Region list, select global (Global).

      For more information, see Eventarc locations.

    3. In the Filters section, in the alerttype list, select one of the following:

      • appDistribution.inAppFeedback: event is sent when a tester submits in-app feedback for a given app
      • appDistribution.newTesterIosDevice: event is sent when a new iOS tester device is registered for a given app
      • billing.planAutomatedUpdate: event is sent when the billing plan for a Firebase project is automatically updated; for example, when a plan is downgraded due to payment issues
      • billing.planUpdate: event is sent when the billing plan for a Firebase project is modified by a user; for example, when a billing account is attached to or detached from a project
      • crashlytics.newAnrIssue: event is sent when an app experiences a new application not responding (ANR) error (not for any subsequent, identical events)
      • crashlytics.newFatalIssue: event is sent when an app experiences a new fatal crash (not for any subsequent, identical events)
      • crashlytics.newNonfatalIssue: event is sent when an app experiences a new non-fatal error (not for any subsequent, identical events)
      • crashlytics.regression: event is sent when an app experiences a crash for an issue marked as closed for a previous app version
      • crashlytics.stabilityDigest: event is sent when there is a notification of the top trending issues in Crashlytics
      • crashlytics.velocity: event is sent when a single issue is responsible for causing a significant number of app sessions to crash

    4. Optionally, you can filter events for a specific Firebase App ID. Click Add filter and specify the appid.

      It must be an exact match.

    Firebase Realtime Database

    Requests to your service are triggered in response to an event when data is created, updated, or deleted in the Firebase Realtime Database.

    1. From the events listed under Direct, select one of the following:

      • google.firebase.database.ref.v1.created: event is sent when data is created in the database
      • google.firebase.database.ref.v1.updated: event is sent when data is updated in the database
      • google.firebase.database.ref.v1.deleted: event is sent when data is deleted in the database
      • google.firebase.database.ref.v1.written: event is sent when data is created, updated, or deleted in the database
    2. In the Region list, select a region.

      Note that this region should match the region of the Firebase Realtime Database instance. For more information, see Eventarc locations.

    3. In the Filters section, select the following:

      1. For the database instance attribute, select one of the following as the operator:
      2. In the Attribute value 1 field, type the name of the database instance to receive events from. Depending on the operator that you chose in the previous step, the attribute value should be the database instance name exactly as is or in a path pattern format.
      3. For the ref attribute, select the operator as Path pattern.
      4. In the Attribute value 2 field, type the path in the database instance to receive events from if data is created, updated, or deleted in that path or any of its children.

    Firebase Remote Config

    Requests to your service are triggered in response to an event when a Remote Config template is updated.

    1. From the events listed under Direct, select google.firebase.remoteconfig.remoteConfig.v1.updated.

    2. In the Region list, select global (Global).

      For more information, see Eventarc locations.

    Firebase Test Lab

    Requests to your service are triggered in response to an event when a TestMatrix has completed.

    1. From the events listed under Direct, select google.firebase.testlab.testMatrix.v1.completed.

    2. In the Region list, select global (Global).

      For more information, see Eventarc locations.

    via Cloud Audit Logs

    Requests to your service are triggered when an audit log is created that matches the trigger's filter criteria. This type of event applies to all event providers.

    1. From the events listed under via Cloud Audit Logs, select one.

    2. Select one of the following:

      • Any resource—This is the default and includes dynamically created resources that have identifiers generated at creation time.

      • Specific resource—You must provide the full resource name.

      • Path pattern—You can filter for resources using a path pattern. For example, type projects/_/buckets/eventarc-bucket/objects/random.txt or type projects/_/buckets/**/r*.txt.

    3. Select a Region.

      Cloud Audit Logs triggers for Eventarc are available in specific regions and in the global region, but are not available in dual-region and multi-region locations. To avoid any performance and data residency issues caused by a global trigger, we recommend that the location match that of the Google Cloud service that is generating events.

      If you specify the global location, you will receive events from all locations for which the event filters match. For example, by creating a global Eventarc trigger, you can receive events from resources in the EU and US multi-regions.

    For more information about capturing events that are triggered when an audit log is created that matches the trigger's filter criteria, see Determine event filters for Cloud Audit Logs.

  9. Select the Service account that invokes your workflow.

    This specifies the IAM service account to which you previously granted the workflows.invoker role so that the account has permission to trigger your workflow.

  10. Click Save trigger.

    The Eventarc triggers is now listed on the Triggers tab of the Workflows Details page.

  11. If you want to update or delete the trigger, you must edit the workflow:

    1. On the Workflow Details page, click Edit.
    2. In the Triggers section, find the trigger you want to update or delete.
    3. Click Edit resource or Delete resource.

Your workflow execution is now triggered by the events that match your trigger's filter criteria.

Create a trigger using Terraform

You can create a trigger for a workflow using Terraform. For details, see Trigger a workflow using Eventarc and Terraform.

What's next