Merge pull request #1413 from Shopify/remove-old-webhook-handler

[Breaking] Remove deprecated ShopifyAPI::Webhooks::Handler interface

Author: lizkenyon

BREAKING_CHANGES_FOR_V15.md

@@ -81,8 +81,8 @@ module WebhookHandler
   extend ShopifyAPI::Webhooks::WebhookHandler
 
   class << self
-    def handle_webhook(data:)
-      puts "Received webhook! topic: #{data.topic} shop: #{data.shop} body: #{data.body} webhook_id: #{data.webhook_id} api_version: #{data.api_version"
+    def handle(data:)
+      puts "Received webhook! topic: #{data.topic} shop: #{data.shop} body: #{data.body} webhook_id: #{data.webhook_id} api_version: #{data.api_version}"
     end
   end
 end

CHANGELOG.md

@@ -3,6 +3,9 @@
 Note: For changes to the API, see https://shopify.dev/changelog?filter=api
 ## Unreleased
 
+### 15.0.0
+
+- ⚠️ [Breaking] Removed deprecated `ShopifyAPI::Webhooks::Handler` interface. Apps must migrate to `ShopifyAPI::Webhooks::WebhookHandler` which provides `webhook_id` and `api_version` in addition to `topic`, `shop`, and `body`. See [BREAKING_CHANGES_FOR_V15.md](BREAKING_CHANGES_FOR_V15.md) for migration guide.
 - Add support for 2025-10 API version
   - Removed deprecated REST resources: `AccessScope`, `Product`, `ProductImage`, `PriceRule`, `ProductListing`, `ProductResourceFeedback`
   - Updated `LATEST_SUPPORTED_ADMIN_VERSION` to `2025-10`

docs/usage/webhooks.md

@@ -29,26 +29,9 @@ module WebhookHandler
 end
 ```
 
-**Note:** As of version 13.5.0 the `ShopifyAPI::Webhooks::Handler` class is still available to be used but will be removed in a future version of the gem.
-
 ### Best Practices
 It is recommended that in order to respond quickly to the Shopify webhook request that the handler not do any heavy logic or network calls, rather it should simply enqueue the work in some job queue in order to be executed later.
 
-### Webhook Handler for versions 13.4.0 and prior
-If you want to register for an http webhook you need to implement a webhook handler which the `shopify_api` gem can use to determine how to process your webhook. You can make multiple implementations (one per topic) or you can make one implementation capable of handling all the topics you want to subscribe to. To do this simply make a module or class that includes or extends `ShopifyAPI::Webhooks::Handler` and implement the handle method which accepts the following named parameters: topic: `String`, shop: `String`, and body: `Hash[String, untyped]`. An example implementation is shown below:
-
-```ruby
-module WebhookHandler
-  extend ShopifyAPI::Webhooks::Handler
-
-  class << self
-    def handle(topic:, shop:, body:)
-      puts "Received webhook! topic: #{topic} shop: #{shop} body: #{body}"
-    end
-  end
-end
-```
-
 ## Add to Webhook Registry
 
 The next step is to add all the webhooks you would like to subscribe to for any shop to the webhook registry. To do this you can call `ShopifyAPI::Webhooks::Registry.add_registration` for each webhook you would like to handle. `add_registration` accepts a topic string, a delivery_method symbol (currently supporting `:http`, `:event_bridge`, and `:pub_sub`), a webhook path (the relative path for an http webhook) and a handler. This only needs to be done once when the app is started and we recommend doing this at the same time that you setup `ShopifyAPI::Context`. An example is shown below to register an http webhook:

lib/shopify_api/webhooks/handler.rb

@@ -11,18 +11,6 @@ class WebhookMetadata < T::Struct
       const :webhook_id, String
     end
 
-    module Handler
-      include Kernel
-      extend T::Sig
-      extend T::Helpers
-      interface!
-
-      sig do
-        abstract.params(topic: String, shop: String, body: T::Hash[String, T.untyped]).void
-      end
-      def handle(topic:, shop:, body:); end
-    end
-
     module WebhookHandler
       include Kernel
       extend T::Sig

lib/shopify_api/webhooks/registration.rb

@@ -13,7 +13,7 @@ class Registration
       sig { returns(String) }
       attr_reader :topic
 
-      sig { returns(T.nilable(T.any(Handler, WebhookHandler))) }
+      sig { returns(T.nilable(WebhookHandler)) }
       attr_reader :handler
 
       sig { returns(T.nilable(T::Array[String])) }
@@ -26,7 +26,7 @@ class Registration
       attr_reader :filter
 
       sig do
-        params(topic: String, path: String, handler: T.nilable(T.any(Handler, WebhookHandler)),
+        params(topic: String, path: String, handler: T.nilable(WebhookHandler),
           fields: T.nilable(T.any(String, T::Array[String])),
           metafield_namespaces: T.nilable(T::Array[String]),
           filter: T.nilable(String)).void

lib/shopify_api/webhooks/registry.rb

@@ -17,7 +17,7 @@ class << self
           params(topic: String,
             delivery_method: Symbol,
             path: String,
-            handler: T.nilable(T.any(Handler, WebhookHandler)),
+            handler: T.nilable(WebhookHandler),
             fields: T.nilable(T.any(String, T::Array[String])),
             filter: T.nilable(String),
             metafield_namespaces: T.nilable(T::Array[String])).void
@@ -195,18 +195,8 @@ def process(request)
             raise Errors::NoWebhookHandler, "No webhook handler found for topic: #{request.topic}."
           end
 
-          if handler.is_a?(WebhookHandler)
-            handler.handle(data: WebhookMetadata.new(topic: request.topic, shop: request.shop,
-              body: request.parsed_body, api_version: request.api_version, webhook_id: request.webhook_id))
-          else
-            handler.handle(topic: request.topic, shop: request.shop, body: request.parsed_body)
-            warning = <<~WARNING
-              DEPRECATED: Use ShopifyAPI::Webhooks::WebhookHandler#handle instead of
-              ShopifyAPI::Webhooks::Handler#handle.
-              https://github.com/Shopify/shopify-api-ruby/blob/main/docs/usage/webhooks.md#create-a-webhook-handler
-            WARNING
-            ShopifyAPI::Logger.deprecated(warning, "15.0.0")
-          end
+          handler.handle(data: WebhookMetadata.new(topic: request.topic, shop: request.shop,
+            body: request.parsed_body, api_version: request.api_version, webhook_id: request.webhook_id))
         end
 
         private

test/test_helpers/fake_webhook_handler.rb

@@ -2,17 +2,16 @@
 # frozen_string_literal: true
 
 require_relative "../../lib/shopify_api/webhooks/handler"
-
 module TestHelpers
   class FakeWebhookHandler
-    include ShopifyAPI::Webhooks::Handler
+    include ShopifyAPI::Webhooks::WebhookHandler
 
     def initialize(handler)
       @handler = handler
     end
 
-    def handle(topic:, shop:, body:)
-      @handler.call(topic, shop, body)
+    def handle(data:)
+      @handler.call(data)
     end
   end
 end

test/test_helpers/new_fake_webhook_handler.rb

@@ -194,7 +194,7 @@ def setup
               delivery_method: protocol,
               path: address,
               handler: TestHelpers::FakeWebhookHandler.new(
-                lambda do |topic, shop, body|
+                lambda do |data|
                 end,
               ),
             )
@@ -219,10 +219,12 @@ def test_process
         handler_called = false
 
         handler = TestHelpers::FakeWebhookHandler.new(
-          lambda do |topic, shop, body,|
-            assert_equal(@topic, topic)
-            assert_equal(@shop, shop)
-            assert_equal({}, body)
+          lambda do |data|
+            assert_equal(@topic, data.topic)
+            assert_equal(@shop, data.shop)
+            assert_equal({}, data.body)
+            assert_equal(@headers["x-shopify-webhook-id"], data.webhook_id)
+            assert_equal(@headers["x-shopify-api-version"], data.api_version)
             handler_called = true
           end,
         )
@@ -242,33 +244,12 @@ def test_process_with_response_as_struct
         handler_called = false
 
         handler = TestHelpers::FakeWebhookHandler.new(
-          lambda do |topic, shop, body,|
-            assert_equal(@topic, topic)
-            assert_equal(@shop, shop)
-            assert_equal({}, body)
-            handler_called = true
-          end,
-        )
-
-        ShopifyAPI::Webhooks::Registry.add_registration(
-          topic: @topic, path: "path", delivery_method: :http, handler: handler,
-        )
-
-        ShopifyAPI::Webhooks::Registry.process(@webhook_request)
-
-        assert(handler_called)
-      end
-
-      def test_process_new_handler
-        handler_called = false
-
-        handler = TestHelpers::NewFakeWebhookHandler.new(
           lambda do |data|
             assert_equal(@topic, data.topic)
             assert_equal(@shop, data.shop)
             assert_equal({}, data.body)
-            assert_equal("b1234-eefd-4c9e-9520-049845a02082", data.webhook_id)
-            assert_equal("2024-01", data.api_version)
+            assert_equal(@headers["x-shopify-webhook-id"], data.webhook_id)
+            assert_equal(@headers["x-shopify-api-version"], data.api_version)
             handler_called = true
           end,
         )
@@ -441,7 +422,7 @@ def add_and_register_webhook(protocol, address, fields: nil, metafield_namespace
           delivery_method: protocol,
           path: address,
           handler: TestHelpers::FakeWebhookHandler.new(
-            lambda do |topic, shop, body|
+            lambda do |data|
             end,
           ),
           fields: fields,