Shopify Flow webhooks

You can receive webhooks from Shopify Flow about the stores that are using your triggers in enabled workflows. You can then use this data to make your app more efficient and reduce running the flowTriggerReceive mutation.

This guide shows you how to configure your app to receive trigger use webhooks from Shopify Flow.

How trigger usage webhooks work

Trigger usage webhooks contain identifying information about the trigger and the store that's 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

The trigger usage webhook (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:

Webhook events

Shopify Flow sends trigger usage webhooks when the following events occur:

  • A merchant enables a workflow that uses your trigger. In this case, the webhook contains "has_enabled_flow": true.
  • Your web server sends a trigger to a store and that store doesn't have a workflow that uses your trigger. In this case, the webhook contains"has_enabled_flow": false.

Web server response time and status codes

When a merchant tries to enable a workflow that uses your trigger, Shopify Flow sends a trigger usage webhook to your web server.

If your web server doesn't respond within 5 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

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

  1. Configure a URL in your web server to listen for the trigger usage webhooks from Shopify Flow.
  2. Configure your web server to verify the HMAC header in the trigger usage webhook with your API secret key.

    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.

  3. Configure your web server to respond within 5 seconds when it receives a trigger usage webhook.

2. Process and store webhook data

After you've added support to list for Shopify Flow webhooks, you can configure your web server to process and store the webhook data.

  1. 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.
  2. Edit your application to send your triggers only to stores that are using your triggers.

3. Configure the webhook

Finally, configure the webhook in your Partner Dashboard. When a merchant enables or disables a workflow that uses your trigger, a webhook is sent from Shopify Flow to your web server.

  1. In your Partner Dashboard, open Apps and then click your test app.
  2. Click Extensions and then click Flow.
  3. Click Configure webhook.
  4. Enter the URL that Shopify Flow will use to send you trigger usage webhooks. This URL can't contain localhost.
  5. Click Save.

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.