From 465d2a0dcf0373a944a6c466957fbd7b557629fa Mon Sep 17 00:00:00 2001 From: Richard Powell Date: Wed, 11 Sep 2024 16:39:54 -0400 Subject: [PATCH 1/3] Update docs to emphasize app-specific webhooks --- docs/shopify_app/webhooks.md | 22 +++++++++++++--------- 1 file changed, 13 insertions(+), 9 deletions(-) diff --git a/docs/shopify_app/webhooks.md b/docs/shopify_app/webhooks.md index f055b0980..10c82e75c 100644 --- a/docs/shopify_app/webhooks.md +++ b/docs/shopify_app/webhooks.md @@ -2,15 +2,17 @@ #### Table of contents -[Webhooks subscription in the app config](#subscribing-to-webhooks-in-the-app-configuration-file) -[Manage webhooks using `ShopifyApp::WebhooksManager`](#manage-webhooks-using-shopifyappwebhooksmanager) +[App-specific webhooks in shopify.app.toml](#subscribing-to-webhooks-in-the-app-configuration-file) +[Manage shop-specific webhooks using `ShopifyApp::WebhooksManager`](#manage-webhooks-using-shopifyappwebhooksmanager) [Mandatory Privacy Webhooks](#mandatory-privacy-webhooks) -## Subscribing to webhooks in the app configuration file -You can now specify the webhooks you want to subscribe to in the `shopify.app.toml` file. Mandatory privacy webhooks and other webhooks can be specified in the `webhooks` section of the configuration file. Learn more about the different way to subscribe to webhooks in the [documentation](https://shopify.dev/docs/apps/build/webhooks/subscribe). +## App-specific webhooks in shopify.app.toml +You can specify app-specific webhooks to subscribe to in the `shopify.app.toml` file. These subscriptions are automatically kept up to date by Shopify so unless your app requires different webhook topics on different shops, you should use app-specific webhooks defined in `shopify.app.toml`. -### Consuming webhooks events -To consume webhooks events where the subscription is done in the `shopify.app.toml` file you can scaffold the necessary files by running the following generator. +Learn more about the different way to subscribe to webhooks in the [documentation](https://shopify.dev/docs/apps/build/webhooks/subscribe). + +### Consuming app-specific webhooks events +To consume app-specific webhooks events wfrom the `shopify.app.toml` file you can scaffold the necessary files by running the following generator. ```bash rails g shopify_app:add_declarative_webhook --topic carts/update --path webhooks/carts_update @@ -18,10 +20,10 @@ rails g shopify_app:add_declarative_webhook --topic carts/update --path webhooks This will add a new controller, job, and route to your application. The controller will verify the webhook and queue the job to process the webhook. The job will be responsible for processing the webhook data. -## Manage webhooks using `ShopifyApp::WebhooksManager` +## Manage shop-specific webhooks using `ShopifyApp::WebhooksManager` -See [`ShopifyApp::WebhooksManager`](/lib/shopify_app/managers/webhooks_manager.rb) -ShopifyApp can manage your app's webhooks for you if you set which webhooks you require in the initializer: +See [`ShopifyApp::WebhooksManager`](/lib/shopify_app/managers/webhooks_manager.rb). +ShopifyApp can manage your app's shop-specific webhooks for you if you set which webhooks you require in the initializer: ```ruby ShopifyApp.configure do |config| @@ -31,6 +33,8 @@ ShopifyApp.configure do |config| end ``` +This method should only be used if you have a good reason not to use app-specific webhooks (such as requiring different topics for different shops). + When the [OAuth callback](/docs/shopify_app/authentication.md#oauth-callback) or token exchange is completed successfully, ShopifyApp will queue a background job which will ensure all the specified webhooks exist for that shop. Because this runs on every OAuth callback, it means your app will always have the webhooks it needs even if the user uninstalls and re-installs the app. ShopifyApp also provides a [WebhooksController](/app/controllers/shopify_app/webhooks_controller.rb) that receives webhooks and queues a job based on the received topic. For example, if you register the webhook from above, then all you need to do is create a job called `CartsUpdateJob`. The job will be queued with 2 params: `shop_domain` and `webhook` (which is the webhook body). From be99cea9196e9f5e18df3c7d7ba1817955dcd32a Mon Sep 17 00:00:00 2001 From: Richard Powell Date: Thu, 12 Sep 2024 07:32:39 -0400 Subject: [PATCH 2/3] Typo fixes from PR review Co-authored-by: Paulo Margarido <64600052+paulomarg@users.noreply.github.com> --- docs/shopify_app/webhooks.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/shopify_app/webhooks.md b/docs/shopify_app/webhooks.md index 10c82e75c..a88e6dbc1 100644 --- a/docs/shopify_app/webhooks.md +++ b/docs/shopify_app/webhooks.md @@ -9,10 +9,10 @@ ## App-specific webhooks in shopify.app.toml You can specify app-specific webhooks to subscribe to in the `shopify.app.toml` file. These subscriptions are automatically kept up to date by Shopify so unless your app requires different webhook topics on different shops, you should use app-specific webhooks defined in `shopify.app.toml`. -Learn more about the different way to subscribe to webhooks in the [documentation](https://shopify.dev/docs/apps/build/webhooks/subscribe). +Learn more about the different ways to subscribe to webhooks in the [documentation](https://shopify.dev/docs/apps/build/webhooks/subscribe). ### Consuming app-specific webhooks events -To consume app-specific webhooks events wfrom the `shopify.app.toml` file you can scaffold the necessary files by running the following generator. +To consume app-specific webhooks events from the `shopify.app.toml` file, you can scaffold the necessary files by running the following generator. ```bash rails g shopify_app:add_declarative_webhook --topic carts/update --path webhooks/carts_update From 3f180ee6888555ac1e437a7df9cf47355f3e9efe Mon Sep 17 00:00:00 2001 From: Richard Powell Date: Thu, 12 Sep 2024 14:03:57 -0400 Subject: [PATCH 3/3] Soften the webhooks docs --- docs/shopify_app/webhooks.md | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/docs/shopify_app/webhooks.md b/docs/shopify_app/webhooks.md index 10c82e75c..96ed9dddd 100644 --- a/docs/shopify_app/webhooks.md +++ b/docs/shopify_app/webhooks.md @@ -2,17 +2,15 @@ #### Table of contents -[App-specific webhooks in shopify.app.toml](#subscribing-to-webhooks-in-the-app-configuration-file) +[App-specific webhooks in shopify.app.toml (recommended)](#subscribing-to-webhooks-in-the-app-configuration-file) [Manage shop-specific webhooks using `ShopifyApp::WebhooksManager`](#manage-webhooks-using-shopifyappwebhooksmanager) [Mandatory Privacy Webhooks](#mandatory-privacy-webhooks) -## App-specific webhooks in shopify.app.toml -You can specify app-specific webhooks to subscribe to in the `shopify.app.toml` file. These subscriptions are automatically kept up to date by Shopify so unless your app requires different webhook topics on different shops, you should use app-specific webhooks defined in `shopify.app.toml`. - -Learn more about the different way to subscribe to webhooks in the [documentation](https://shopify.dev/docs/apps/build/webhooks/subscribe). +## App-specific webhooks in shopify.app.toml (recommended) +You can specify app-specific webhooks to subscribe to in the `shopify.app.toml` file. These subscriptions are easier to manage because they are kept up to date by Shopify. In many cases they will be sufficient. Please read [app-specific vs shop-specific subscriptions](https://shopify.dev/docs/apps/build/webhooks/subscribe#app-specific-vs-shop-specific-subscriptions) to understand when you might need shop-specific webhooks. ### Consuming app-specific webhooks events -To consume app-specific webhooks events wfrom the `shopify.app.toml` file you can scaffold the necessary files by running the following generator. +To consume app-specific webhooks events from the `shopify.app.toml` file you can scaffold the necessary files by running the following generator. ```bash rails g shopify_app:add_declarative_webhook --topic carts/update --path webhooks/carts_update