Trigger usage webhooks

Receive webhooks from Shopify Flow about the stores that are using your triggers in enabled workflows. Use this data to make your application more efficient and reduce unnecessary flowTriggerReceive GraphQL requests.

Trigger usage webhooks contain identifying information about the trigger and store that is 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 send trigger requests to only those stores.

Webhook reference

The trigger usage webhook (HTTP post) 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 ISO8601 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, overwrite this payload's information in your datastore. Conversely, if you receive a timestamp that is older than the information in your datastore, ignore this payload.

2019-01-25T16:44:10.999Z

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

{
  "flow_trigger_definition_id": "Add row to spreadsheet",
  "has_enabled_flow": false,
  "shop_id": "690933842",
  "shopify_domain": "johnapparel.myshopify.com",
  "timestamp": "2019-01-25T16:44:10.999Z"
}

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_enablerd_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 it responds with a different status code, then your merchant can't enable that workflow. Your merchant will receive a notification in the Shopify Flow app that tells them to try enabling the workflow at a later time.

Add support to listen for Shopify Flow webhooks in your web server

  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.

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

Configure the webhook in the Shopify Partner Dashboard

  1. In the Partner Dashboard, open Apps and then click your test app.

  2. Click Extensions > Shopify Flow:

    Shopify Flow listed under Extensions
    If you don't see Shopify Flow listed under Extensions, then you need to add the extension to your app.

  3. Click Configure webhook.

  4. Enter the URL that Shopify Flow will use to send you trigger usage webhooks. This URL cannot contain localhost.

  5. Click Save.

Now whenever a merchant enables or disables a workflow that uses your trigger, a webhook is sent from Shopify Flow to your web server.

Sign up for a Partner account to get started.

Sign up