Extend webhook registration to support filters

CHANGELOG.md

@@ -3,6 +3,7 @@
 Note: For changes to the API, see https://shopify.dev/changelog?filter=api
 ## Unreleased
 
+- [#1347](https://github.com/Shopify/shopify-api-ruby/pull/1347) Extend webhook registration to support filters
 - [#1344](https://github.com/Shopify/shopify-api-ruby/pull/1344) Allow ShopifyAPI::Webhooks::Registry to update a webhook when fields or metafield_namespaces are changed.
 - [#1343](https://github.com/Shopify/shopify-api-ruby/pull/1343) Make ShopifyAPI::Context::scope parameter optional. `scope` defaults to empty list `[]`.
 

docs/usage/webhooks.md

@@ -82,6 +82,17 @@ registration = ShopifyAPI::Webhooks::Registry.add_registration(
 )
 ```
 
+If you need to filter the webhooks you want to receive, you can use a [webhooks filter](https://shopify.dev/docs/apps/build/webhooks/customize/filters), which can be specified on registration through the `filter` parameter.
+
+```ruby
+registration = ShopifyAPI::Webhooks::Registry.add_registration(
+  topic: "products/update",
+  delivery_method: :http,
+  handler: WebhookHandler,
+  filter: "variants.price:>=10.00"
+)
+```
+
 **Note**: The webhooks you register with Shopify are saved in the Shopify platform, but the local `ShopifyAPI::Webhooks::Registry` needs to be reloaded whenever your server restarts.
 
 ### EventBridge and PubSub Webhooks

lib/shopify_api/rest/resources/2024_07/webhook.rb

@@ -23,6 +23,7 @@ def initialize(session: ShopifyAPI::Context.active_session, from_hash: nil)
       @api_version = T.let(nil, T.nilable(String))
       @created_at = T.let(nil, T.nilable(String))
       @fields = T.let(nil, T.nilable(T::Array[T.untyped]))
+      @filter = T.let(nil, T.nilable(String))
       @format = T.let(nil, T.nilable(String))
       @id = T.let(nil, T.nilable(Integer))
       @metafield_namespaces = T.let(nil, T.nilable(T::Array[T.untyped]))

lib/shopify_api/rest/resources/2024_10/webhook.rb

@@ -23,6 +23,7 @@ def initialize(session: ShopifyAPI::Context.active_session, from_hash: nil)
       @api_version = T.let(nil, T.nilable(String))
       @created_at = T.let(nil, T.nilable(String))
       @fields = T.let(nil, T.nilable(T::Array[T.untyped]))
+      @filter = T.let(nil, T.nilable(String))
       @format = T.let(nil, T.nilable(String))
       @id = T.let(nil, T.nilable(Integer))
       @metafield_namespaces = T.let(nil, T.nilable(T::Array[T.untyped]))

lib/shopify_api/webhooks/registration.rb

@@ -22,18 +22,23 @@ class Registration
       sig { returns(T.nilable(T::Array[String])) }
       attr_reader :metafield_namespaces
 
+      sig { returns(T.nilable(String)) }
+      attr_reader :filter
+
       sig do
         params(topic: String, path: String, handler: T.nilable(T.any(Handler, WebhookHandler)),
           fields: T.nilable(T.any(String, T::Array[String])),
-          metafield_namespaces: T.nilable(T::Array[String])).void
+          metafield_namespaces: T.nilable(T::Array[String]),
+          filter: T.nilable(String)).void
       end
-      def initialize(topic:, path:, handler: nil, fields: nil, metafield_namespaces: nil)
+      def initialize(topic:, path:, handler: nil, fields: nil, metafield_namespaces: nil, filter: nil)
         @topic = T.let(topic.gsub("/", "_").upcase, String)
         @path = path
         @handler = handler
         fields_array = fields.is_a?(String) ? fields.split(FIELDS_DELIMITER) : fields
         @fields = T.let(fields_array&.map(&:strip)&.compact, T.nilable(T::Array[String]))
         @metafield_namespaces = T.let(metafield_namespaces&.map(&:strip)&.compact, T.nilable(T::Array[String]))
+        @filter = filter
       end
 
       sig { abstract.returns(String) }
@@ -54,6 +59,7 @@ def build_check_query; end
           current_address: T.nilable(String),
           fields: T::Array[String],
           metafield_namespaces: T::Array[String],
+          filter: T.nilable(String),
         })
       end
       def parse_check_result(body); end
@@ -88,6 +94,7 @@ def subscription_response_attributes
         attributes = ["id"]
         attributes << "includeFields" if @fields
         attributes << "metafieldNamespaces" if @metafield_namespaces
+        attributes << "filter" if @filter
         attributes
       end
     end

lib/shopify_api/webhooks/registrations/event_bridge.rb

@@ -14,7 +14,8 @@ def callback_address
 
         sig { override.returns(T::Hash[Symbol, String]) }
         def subscription_args
-          { arn: callback_address, includeFields: fields, metafieldNamespaces: metafield_namespaces }.compact
+          { arn: callback_address, includeFields: fields,
+            metafieldNamespaces: metafield_namespaces, filter: filter, }.compact
         end
 
         sig { override.params(webhook_id: T.nilable(String)).returns(String) }
@@ -32,6 +33,7 @@ def build_check_query
                     id
                     includeFields
                     metafieldNamespaces
+                    filter
                     endpoint {
                       __typename
                       ... on WebhookEventBridgeEndpoint {
@@ -51,23 +53,26 @@ def build_check_query
             current_address: T.nilable(String),
             fields: T::Array[String],
             metafield_namespaces: T::Array[String],
+            filter: T.nilable(String),
           })
         end
         def parse_check_result(body)
           edges = body.dig("data", "webhookSubscriptions", "edges") || {}
           webhook_id = nil
           fields = []
           metafield_namespaces = []
+          filter = nil
           current_address = nil
           unless edges.empty?
             node = edges[0]["node"]
             webhook_id = node["id"].to_s
             current_address = node["endpoint"]["arn"].to_s
             fields = node["includeFields"] || []
             metafield_namespaces = node["metafieldNamespaces"] || []
+            filter = node["filter"].to_s
           end
           { webhook_id: webhook_id, current_address: current_address, fields: fields,
-            metafield_namespaces: metafield_namespaces, }
+            metafield_namespaces: metafield_namespaces, filter: filter, }
         end
       end
     end

lib/shopify_api/webhooks/registrations/http.rb

@@ -20,7 +20,8 @@ def callback_address
 
         sig { override.returns(T::Hash[Symbol, String]) }
         def subscription_args
-          { callbackUrl: callback_address, includeFields: fields, metafieldNamespaces: metafield_namespaces }.compact
+          { callbackUrl: callback_address, includeFields: fields,
+            metafieldNamespaces: metafield_namespaces, filter: filter, }.compact
         end
 
         sig { override.params(webhook_id: T.nilable(String)).returns(String) }
@@ -38,6 +39,7 @@ def build_check_query
                     id
                     includeFields
                     metafieldNamespaces
+                    filter
                     endpoint {
                       __typename
                       ... on WebhookHttpEndpoint {
@@ -57,13 +59,15 @@ def build_check_query
             current_address: T.nilable(String),
             fields: T::Array[String],
             metafield_namespaces: T::Array[String],
+            filter: T.nilable(String),
           })
         end
         def parse_check_result(body)
           edges = body.dig("data", "webhookSubscriptions", "edges") || {}
           webhook_id = nil
           fields = []
           metafield_namespaces = []
+          filter = nil
           current_address = nil
           unless edges.empty?
             node = edges[0]["node"]
@@ -76,9 +80,10 @@ def parse_check_result(body)
               end
             fields = node["includeFields"] || []
             metafield_namespaces = node["metafieldNamespaces"] || []
+            filter = node["filter"].to_s
           end
           { webhook_id: webhook_id, current_address: current_address, fields: fields,
-            metafield_namespaces: metafield_namespaces, }
+            metafield_namespaces: metafield_namespaces, filter: filter, }
         end
       end
     end

lib/shopify_api/webhooks/registrations/pub_sub.rb

@@ -18,7 +18,7 @@ def subscription_args
           project = project_topic_pair[0]
           topic = project_topic_pair[1]
           { pubSubProject: project, pubSubTopic: topic, includeFields: fields,
-            metafieldNamespaces: metafield_namespaces, }.compact
+            metafieldNamespaces: metafield_namespaces, filter: filter, }.compact
         end
 
         sig { override.params(webhook_id: T.nilable(String)).returns(String) }
@@ -36,6 +36,7 @@ def build_check_query
                     id
                     includeFields
                     metafieldNamespaces
+                    filter
                     endpoint {
                       __typename
                       ... on WebhookPubSubEndpoint {
@@ -56,13 +57,15 @@ def build_check_query
             current_address: T.nilable(String),
             fields: T::Array[String],
             metafield_namespaces: T::Array[String],
+            filter: T.nilable(String),
           })
         end
         def parse_check_result(body)
           edges = body.dig("data", "webhookSubscriptions", "edges") || {}
           webhook_id = nil
           fields = []
           metafield_namespaces = []
+          filter = nil
           current_address = nil
           unless edges.empty?
             node = edges[0]["node"]
@@ -71,9 +74,10 @@ def parse_check_result(body)
               "pubsub://#{node["endpoint"]["pubSubProject"]}:#{node["endpoint"]["pubSubTopic"]}"
             fields = node["includeFields"] || []
             metafield_namespaces = node["metafieldNamespaces"] || []
+            filter = node["filter"].to_s
           end
           { webhook_id: webhook_id, current_address: current_address, fields: fields,
-            metafield_namespaces: metafield_namespaces, }
+            metafield_namespaces: metafield_namespaces, filter: filter, }
         end
       end
     end

lib/shopify_api/webhooks/registry.rb

@@ -19,23 +19,25 @@ class << self
             path: String,
             handler: T.nilable(T.any(Handler, WebhookHandler)),
             fields: T.nilable(T.any(String, T::Array[String])),
+            filter: T.nilable(String),
             metafield_namespaces: T.nilable(T::Array[String])).void
         end
-        def add_registration(topic:, delivery_method:, path:, handler: nil, fields: nil, metafield_namespaces: nil)
+        def add_registration(topic:, delivery_method:, path:, handler: nil, fields: nil, filter: nil,
+          metafield_namespaces: nil)
           @registry[topic] = case delivery_method
           when :pub_sub
             Registrations::PubSub.new(topic: topic, path: path, fields: fields,
-              metafield_namespaces: metafield_namespaces)
+              metafield_namespaces: metafield_namespaces, filter: filter)
           when :event_bridge
             Registrations::EventBridge.new(topic: topic, path: path, fields: fields,
-              metafield_namespaces: metafield_namespaces)
+              metafield_namespaces: metafield_namespaces, filter: filter)
           when :http
             unless handler
               raise Errors::InvalidWebhookRegistrationError, "Cannot create an Http registration without a handler."
             end
 
             Registrations::Http.new(topic: topic, path: path, handler: handler,
-              fields: fields, metafield_namespaces: metafield_namespaces)
+              fields: fields, metafield_namespaces: metafield_namespaces, filter: filter)
           else
             raise Errors::InvalidWebhookRegistrationError,
               "Unsupported delivery method #{delivery_method}. Allowed values: {:http, :pub_sub, :event_bridge}."
@@ -223,10 +225,12 @@ def webhook_registration_needed?(client, registration)
           parsed_check_result = registration.parse_check_result(T.cast(check_response.body, T::Hash[String, T.untyped]))
           registration_fields = registration.fields || []
           registration_metafield_namespaces = registration.metafield_namespaces || []
+          registration_filter = registration.filter
 
           must_register = parsed_check_result[:current_address] != registration.callback_address ||
             parsed_check_result[:fields].sort != registration_fields.sort ||
-            parsed_check_result[:metafield_namespaces].sort != registration_metafield_namespaces.sort
+            parsed_check_result[:metafield_namespaces].sort != registration_metafield_namespaces.sort ||
+            parsed_check_result[:filter] != registration_filter
 
           { webhook_id: parsed_check_result[:webhook_id], must_register: must_register }
         end

test/webhooks/registry_test.rb

@@ -53,6 +53,7 @@ def setup
               address,
               fields: "field1, field2",
               metafield_namespaces: ["namespace1", "namespace2"],
+              filter: "id:*",
             )
 
             # Then
@@ -72,6 +73,7 @@ def setup
               address,
               fields: ["field1", "field2"],
               metafield_namespaces: ["namespace1", "namespace2"],
+              filter: "id:*",
             )
 
             # Then
@@ -156,6 +158,27 @@ def setup
               update_registration_response.body)
           end
 
+          define_method("test_#{protocol}_update_registration_filter_with_address_#{address}") do
+            # Given
+            setup_queries_and_responses(
+              [queries[protocol][:check_query], queries[protocol][:register_update_query_with_filter]],
+              [queries[protocol][:check_existing_response],
+               queries[protocol][:register_update_with_filter_response],],
+            )
+
+            # When
+            update_registration_response = add_and_register_webhook(
+              protocol,
+              address,
+              filter: "id:*",
+            )
+
+            # Then
+            assert(update_registration_response.success)
+            assert_equal(queries[protocol][:register_update_with_filter_response],
+              update_registration_response.body)
+          end
+
           define_method("test_raises_on_#{protocol}_registration_check_error_with_address_#{address}") do
             # Given
             ShopifyAPI::Webhooks::Registry.clear
@@ -412,7 +435,7 @@ def setup_queries_and_responses(queries, responses)
         end
       end
 
-      def add_and_register_webhook(protocol, address, fields: nil, metafield_namespaces: nil)
+      def add_and_register_webhook(protocol, address, fields: nil, metafield_namespaces: nil, filter: nil)
         ShopifyAPI::Webhooks::Registry.add_registration(
           topic: @topic,
           delivery_method: protocol,
@@ -423,6 +446,7 @@ def add_and_register_webhook(protocol, address, fields: nil, metafield_namespace
           ),
           fields: fields,
           metafield_namespaces: metafield_namespaces,
+          filter: filter,
         )
         update_registration_response = ShopifyAPI::Webhooks::Registry.register_all(
           session: @session,