Track Flow lifecycle events

This guide explains how to configure your app to receive trigger lifecycle callbacks from Shopify Flow.

When creating a trigger, configuring a lifecycle callback enables your app to receive notifications from Shopify Flow about stores using the trigger and communicate changes in workflow status (e.g., enabling or disabling a workflow) back to the app. This helps optimize app performance by ensuring that trigger-related operations are only performed for stores that actually need them.

Apps must be properly configured to respond to trigger lifecycle callbacks. When a merchant attempts to enable a workflow that uses the trigger, Shopify Flow sends a lifecycle callback to the app's web server. If it doesn't promptly receive a response or receives a response with an HTTP status code that isn't 2xx, then the merchant can't enable the workflow and make use of the trigger.

How trigger lifecycle callbacks work

Anchor link to section titled "How trigger lifecycle callbacks work"

Trigger lifecycle callbacks contain identifying information about the trigger and the store using it and indicate whether the trigger is being used. You can use this information to track the stores that are currently using your triggers and then send trigger requests to only those stores.

Properties

Anchor link to section titled "Properties"

The trigger lifecycle callback (HTTP POST request) is formatted in JSON and it contains the following properties:

Property	Data type	Description	Example
`flow_trigger_definition_id`	String	The unique identifier for your Shopify Flow trigger.	Add row to spreadsheet
`has_enabled_flow`	Boolean	Whether the store has an enabled workflow that uses your trigger. Valid values: `true`: There is at least one workflow that is enabled and that uses your trigger. `false`: There are no enabled workflows that use your trigger.	true
`shop_id`	Number	The unique identifier for the Shopify store.	690933842
`shopify_domain`	String	The myshopify domain of the Shopify store.	johnsapparel.myshopify.com
`timestamp`	ISO 8601 date and timestamp	The time when the notification was created. Notifications with newer timestamps should take precedence. If you already have a timestamp in your datastore and you receive a newer timestamp, then overwrite this payload's information in your datastore. Conversely, if you receive a timestamp that is older than the information in your datastore, then ignore this payload.	2019-01-25T16:44:10.999Z

The following is an example body of a usage notification (HTTP POST) request:

Callback events

Anchor link to section titled "Callback events"

Shopify Flow sends trigger lifecycle callbacks when the following events occur:

When a merchant activates a workflow that uses your trigger, the callback contains "has_enabled_flow": true.
When a merchant deactivates a workflow that uses your trigger, the callback contains "has_enabled_flow": false.

Web server response time and status codes

Anchor link to section titled "Web server response time and status codes"

When a merchant tries to enable a workflow that uses your trigger, Shopify Flow sends a trigger lifecycle callback to your web server. If your web server doesn't respond within five seconds, or if it responds with a different status code, then the merchant can't enable that workflow. The merchant receives a notification in the Shopify Flow app that tells them to try enabling the workflow at a later time.

1. Configure your web server

Anchor link to section titled "1. Configure your web server"

To begin, configure your web server to listen for Shopify Flow callbacks.

Configure a URL in your web server to listen for the trigger lifecycle callbacks from Shopify Flow.
Configure your web server to verify the HMAC header in the trigger lifecycle callback with your client secret.

The HMAC header is located in the following HTTP header: x-shopify-hmac-sha256. If you are using a Ruby-based web framework, then the header is http-x-shopify-hmac-sha256.
Configure your web server to respond within 5 seconds when it receives a trigger lifecycle callback.

2. Process and store callback data

Anchor link to section titled "2. Process and store callback data"

After you've added support to listen for Shopify Flow callbacks, you can configure your web server to process and store the callback data.

Save the list of stores that are using your triggers in a persistent datastore. Use the timestamp property to make sure that you don't overwrite an existing entry with older information.
Edit your application to send your triggers only to stores that are using your triggers.

3. Configure the callback

Anchor link to section titled "3. Configure the callback"

Finally, configure the callback in the CLI:

Run shopify app generate extension.
Select Flow trigger lifecycle callback.
Change the URL in the generated TOML to the URL configured on the web server.
Run shopify app deploy.

Next steps

Anchor link to section titled "Next steps"

Familiarize yourself with Shopify Flow and learn about building connectors.
Connect your app to Shopify Flow so that events that occur in your app can trigger workflows.
Connect your app to Shopify Flow so that your app receives data and information when a workflow action runs.