Add support for filters in webhook registration

CHANGELOG.md

@@ -1,5 +1,7 @@
 Unreleased
 ----------
+
+- Add support for filters in webhook registration [1923](https://github.com/Shopify/shopify_app/pull/1923)
 -  Make `ShopifyApp.configuration.scope` default to empty list `[]` [1913](https://github.com/Shopify/shopify_app/pull/1913)
 
 22.4.0 (August 22, 2024)

Gemfile.lock

@@ -7,7 +7,7 @@ PATH
       jwt (>= 2.2.3)
       rails (> 5.2.1)
       redirect_safely (~> 1.0)
-      shopify_api (>= 14.3.0, < 15.0)
+      shopify_api (>= 14.7.0, < 15.0)
       sprockets-rails (>= 2.0.0)
 
 GEM
@@ -219,7 +219,7 @@ GEM
     ruby-progressbar (1.13.0)
     ruby2_keywords (0.0.5)
     securerandom (0.2.2)
-    shopify_api (14.3.0)
+    shopify_api (14.7.0)
       activesupport
       concurrent-ruby
       hash_diff

docs/shopify_app/webhooks.md

@@ -62,13 +62,27 @@ ShopifyApp.configure do |config|
   config.webhooks = [
     {
       topic: 'orders/create',
-      path: 'api/webhooks/order_create',
+      path: 'api/webhooks/orders_create',
       metafield_namespaces: ['app-namespace'],
     },
   ]
 end
 ```
 
+If you need to filter by webhook fields, you can register a webhook with a `filter` parameter. The documentation for Webhook filters can be found [here](https://shopify.dev/docs/apps/build/webhooks/customize/filters).
+
+```ruby
+ShopifyApp.configure do |config|
+  config.webhooks = [
+    {
+      topic: 'products/update',
+      path: 'api/webhooks/products_update',
+      filter: "variants.price:>=10.00",
+    },
+  ]
+end
+```
+
 If you'd rather implement your own controller then you'll want to use the [`ShopifyApp::WebhookVerification`](/lib/shopify_app/controller_concerns/webhook_verification.rb) module to verify your webhooks, example:
 
 ```ruby

lib/shopify_app/managers/webhooks_manager.rb

@@ -52,6 +52,7 @@ def add_registrations
             path: webhook_path,
             handler: delivery_method == :http ? webhook_job_klass(webhook_path) : nil,
             fields: attributes[:fields],
+            filter: attributes[:filter],
             metafield_namespaces: attributes[:metafield_namespaces],
           )
         end

shopify_app.gemspec

@@ -18,7 +18,7 @@ Gem::Specification.new do |s|
   s.add_runtime_dependency("addressable", "~> 2.7")
   s.add_runtime_dependency("rails", "> 5.2.1")
   s.add_runtime_dependency("redirect_safely", "~> 1.0")
-  s.add_runtime_dependency("shopify_api", ">= 14.3.0", "< 15.0")
+  s.add_runtime_dependency("shopify_api", ">= 14.7.0", "< 15.0")
   s.add_runtime_dependency("sprockets-rails", ">= 2.0.0")
   # Deprecated: move to development dependencies when releasing v23
   s.add_runtime_dependency("jwt", ">= 2.2.3")

test/shopify_app/managers/webhooks_manager_test.rb

@@ -23,6 +23,7 @@ class ShopifyApp::WebhooksManagerTest < ActiveSupport::TestCase
       handler: OrdersUpdatedJob,
       fields: nil,
       metafield_namespaces: nil,
+      filter: nil,
     }
 
     ShopifyAPI::Webhooks::Registry.expects(:add_registration).with(**expected_hash).once
@@ -42,6 +43,7 @@ class ShopifyApp::WebhooksManagerTest < ActiveSupport::TestCase
       handler: OrdersUpdatedJob,
       fields: nil,
       metafield_namespaces: nil,
+      filter: nil,
     }
 
     ShopifyAPI::Webhooks::Registry.expects(:add_registration).with(**expected_hash).once
@@ -57,6 +59,31 @@ class ShopifyApp::WebhooksManagerTest < ActiveSupport::TestCase
     ShopifyApp::WebhooksManager.add_registrations
   end
 
+  test "#add_registrations includes filters" do
+    expected_hash = {
+      topic: "orders/updated",
+      delivery_method: :http,
+      path: "/webhooks/orders_updated",
+      handler: OrdersUpdatedJob,
+      fields: nil,
+      metafield_namespaces: nil,
+      filter: "id:*",
+    }
+
+    ShopifyAPI::Webhooks::Registry.expects(:add_registration).with(**expected_hash).once
+    ShopifyApp.configure do |config|
+      config.webhooks = [
+        {
+          topic: "orders/updated",
+          address: "https://some.domain.over.the.rainbow.com/webhooks/orders_updated",
+          filter: "id:*",
+        },
+      ]
+    end
+
+    ShopifyApp::WebhooksManager.add_registrations
+  end
+
   test "#add_registrations raises an error when missing path and address" do
     ShopifyApp.configure do |config|
       config.webhooks = [