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.
What you'll learn
Anchor link to section titled "What 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.
App-specific subscriptions
Anchor link to section titled "App-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.
Shop-specific subscriptions
Anchor link to section titled "Shop-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.
App-specific vs. Shop-specific subscriptions
Anchor link to section titled "App-specific vs. Shop-specific subscriptions"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.
| 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. |
Subscribing to topics as a custom app
Anchor link to section titled "Subscribing to topics as a custom app"Webhooks are available for custom apps to use. However, since custom apps are created in the Shopify admin, they cannot take advantage of the tooling available through the Shopify CLI, including subscribing the webhook topics using an 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.
- 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.