About managing webhook subscriptions
You can configure your app to subscribe to webhook topics in the following ways:
- If your app was created with the Shopify CLI, then use your app configuration file. This is the recommended method for getting started quickly and for subscribing to webhooks for all shops that your app is installed on.
- If your app was created with the Shopify CLI, then you can also use the GraphQL Admin API. This is most useful in cases where your webhook subscriptions might depend on which shop your app is installed on.
- If your app is a custom app, then use the Shopify admin to create your app and manage scopes, and the GraphQL Admin API to subscribe to webhook topics.
Once a subscription has been configured correctly, Shopify will send webhooks to your app with data about events that have occurred on a shop, related to the topics you have subscribed to.
Anchor to What you'll learnWhat you'll learn
In this section, you will learn about:
- How to quickly get started and create your first webhook subscription
- This includes details about the use cases, trade-offs, and constraints for each. Shopify's recommendations across different subscription mechanisms (using your app configuration file vs. the Admin API), delivery methods (cloud-based vs. HTTPS) and technologies available to you. This includes details about the use cases, trade-offs, and constraints for each.
Webhooks are divided by topic. Refer to the Webhooks references for the complete list of supported webhook topics.
Anchor to App-specific subscriptionsApp-specific subscriptions
You can subscribe your app to webhook topics using your app configuration file, rather than using the Admin API. This allows your subscriptions to be configured and managed across all shops that your app is installed on. This also makes subscription configuration and management easy when you are getting started with Shopify's webhooks. Shopify recommends subscribing to webhooks using this approach.
You must use Shopify CLI version 3.63.0 or higher to configure app-specific webhook subscriptions.
Anchor to Shop-specific subscriptionsShop-specific subscriptions
To subscribe your app to webhook topics where the configuration depends on the shop your app is installed on, use the GraphQL Admin API.
Anchor to App-specific vs. Shop-specific subscriptionsApp-specific vs.
If you use the Shopify CLI to build your app, then there are important differences to be aware of when configuring app-specific subscriptions using your app configuration file versus configuring shop-specific subscriptions using the Admin API.
If you have shop-specific subscriptions already, and are migrating your app to app-specific subscriptions, then make sure you first remove any existing webhook subscriptions to the same topics. This avoids potential conflicts and duplicate notifications.
- Check the list of existing shop-specific webhook topics your app is subscribed to by using the GraphQL Admin API
webhookSubscriptionsquery. - Delete the relevant queries, subscription, and handler code from your app.
- Deploy a new version of your app by running
shopify app deploy. You can check that your subscriptions have been deleted by checking the Versions page for your app in the Partner Dashboard. - Configure your app to subscribe to app-specific subscriptions. Refer to the create a subscription tutorial to get started.
| App-specific | Shop-specifc | Additional Resources | |
|---|---|---|---|
| Interface for management | Your app configuration file | GraphQL Admin API | |
| Troubleshooting | Failing webhook subscriptions that are not fixed will not be deleted by Shopify | Failing webhook subscriptions that are not fixed will be deleted by Shopify | Troubleshoot your webhooks. |
| Viewing subscriptions | Available under Subscriptions in your app dashboard > Versions > Configuration | You can query the GraphQL Admin API to get a list of all webhook subscriptions | GraphQL Admin API Query example. |
| Differentiating between methods | Available in the Subscription Method field, per delivery log in your app dashboard > Insights > Delivery logs | Available in the "Subscription Method" field, per delivery log in your app dashboard > Insights > Delivery logs | |
| Identifying your subscriptions | No ID, denoted config-managed | Available as the Subscription ID field, in your app dashboard > Insights > Webhooks > Select a topic to view Delivery Logs | Subscription IDs are only available for API-managed configurations. A subscription ID can be used to query the subscription. |
| Scopes | Requires scopes to be specified in your app configuration file | Scopes can be configured in your app configuration file or in your Partners dashboard. They cannot be subscribed to using the Admin API | Learn more about Shopify access and approval scopes. |
| Metafield Namespaces | Does not support using metafieldNamespaces | metafieldNamespaces can be used as an input field for a webhook subscription in the Admin API | Learn how in the GraphQL Admin API examples. |
| Configuring compliance webhook topics | Compliance topics can be subscribed to using your app configuration file or the Partners dashboard | Compliance topics can be configured in your app configuration file or in your Partners dashboard. They cannot be subscribed to using the Admin API | Refer to examples in the Privacy law compliance documentation and see which scopes are required for these topics in the Webhooks reference. |
| Topics | Supports every topic except for product_feeds/full_sync, product_feeds/full_sync_finish, and product_feeds/incremental_sync | Supports every topic | Refer to the list of webhook topics. |
Anchor to Subscribing to topics as a custom appSubscribing to topics as a custom app
Webhooks are available for all custom apps to use. However, custom apps created in the Shopify admin cannot take advantage of the tooling available through the Shopify CLI, including subscribing to webhook topics using the app configuration file.
This means that webhook subscriptions must be set up and configured using the GraphQL Admin API.
- Create an app in the Shopify Admin and install it on your test shop to get your Admin API Access token.
- Configure your Admin API scopes by selecting the scopes that you'll need for each webhook topic that you intend to subscribe to. Learn more about which topics require which Shopify scopes in the Webhooks reference.
- Subscribe to webhook topics using the Admin API and your Admin API access token.
Anchor to Next stepsNext steps
- Get started by setting up your first webhook subscription.
- Learn how to subscribe to webhooks using the GraphQL Admin API.
- Understand the differences between cloud-based event bus delivery of webhooks, and HTTPS delivery.