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.

• The Workflows deduplication window to ensure exactly-once processing of events is 24 hours.

• 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.

• In projects protected by a service perimeter, when routing events to Workflows destinations for which the Pub/Sub push endpoint is set to a Workflows execution, you can only create new Pub/Sub push subscriptions through Eventarc. Note that the service account used for push authentication for the Workflows endpoint must be included in the service perimeter. For more information, see Set up a service perimeter using VPC Service Controls.

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 the gcloud instructions in the "Create a trigger" section when creating a trigger for a specific provider, event type, and Workflows destination.

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 Google Cloud 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 don't already have a workflow that you want to trigger, create and deploy one.

2. In the Google Cloud 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. Follow the instructions to create a trigger for a specific provider, event type, and Workflows destination and refer to the Console instructions in the "Create a trigger" section.

7. 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.

8. Click Save trigger.

   Note: If you are updating an existing workflow, you do not need to redeploy the workflow. However, if you are creating a new workflow, you must also deploy the workflow.

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

9. 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

• Learn more about Eventarc