breaking change: include the env param in the method signature for .call

Author: GrantBirki

README.md

@@ -58,7 +58,7 @@ Here is a very high-level overview of how Hooks works:
     ```ruby
     # file: plugins/handlers/my_custom_handler.rb
     class MyCustomHandler < Hooks::Plugins::Handlers::Base
-      def call(payload:, headers:, config:)
+      def call(payload:, headers:, env:, config:)
         # Process the incoming webhook - optionally use the payload and headers
         # to perform some action or validation
         # For this example, we will just return a success message
@@ -233,7 +233,7 @@ Create custom handler plugins in the `plugins/handlers` directory to process inc
 ```ruby
 # file: plugins/handlers/hello_handler.rb
 class HelloHandler < Hooks::Plugins::Handlers::Base
-  def call(payload:, headers:, config:)
+  def call(payload:, headers:, env:, config:)
     # Process the incoming webhook - optionally use the payload and headers
     # to perform some action or validation
     # For this example, we will just return a success message
@@ -251,7 +251,7 @@ And another handler plugin for the `/goodbye` endpoint:
 ```ruby
 # file: plugins/handlers/goodbye_handler.rb
 class GoodbyeHandler < Hooks::Plugins::Handlers::Base
-  def call(payload:, headers:, config:)
+  def call(payload:, headers:, env:, config:)
     # Ditto for the goodbye endpoint
     {
       message: "goodbye webhook processed successfully",

docs/design.md

@@ -33,7 +33,7 @@ Note: The `hooks` gem name is already taken on RubyGems, so this project is name
 2. **Plugin Architecture**
 
    * **Team Handlers**: `class MyHandler < Hooks::Plugins::Handlers::Base`
-     * Must implement `#call(payload:, headers:, config:)` method
+     * Must implement `#call(payload:, headers:, env:, config:)` method
      * `payload`: parsed request body (JSON Hash or raw String)
      * `headers`: HTTP headers as Hash with string keys
      * `config`: merged endpoint configuration including `opts` section
@@ -230,7 +230,7 @@ endpoints_dir:   ./config/endpoints # directory containing endpoint configs
        * **Before**: enforce `request_limit`, `request_timeout`
        * **Signature**: call custom or default validator
        * **Hooks**: run `on_request` plugins
-     * **Handler**: invoke `MyHandler.new.call(payload:, headers:, config:)`
+     * **Handler**: invoke `MyHandler.new.call(payload:, headers:, env:, config:)`
      * **After**: run `on_response` plugins
      * **Rescue**: on exception, run `on_error`, rethrow or format JSON error
 
@@ -528,9 +528,10 @@ Base class for all webhook handlers.
 class MyHandler < Hooks::Plugins::Handlers::Base
   # @param payload [Hash, String] Parsed request body or raw string
   # @param headers [Hash<String, String>] HTTP headers
+  # @param env [Hash] Rack environment (includes request context)
   # @param config [Hash] Merged endpoint configuration
   # @return [Hash, String, nil] Response body (auto-converted to JSON)
-  def call(payload:, headers:, config:)
+  def call(payload:, headers:, env:, config:)
     # Handler implementation
     { status: "processed", id: generate_id }
   end

docs/handler_plugins.md

@@ -17,9 +17,10 @@ class Example < Hooks::Plugins::Handlers::Base
   #
   # @param payload [Hash, String] webhook payload (pure JSON with string keys)
   # @param headers [Hash] HTTP headers (string keys, optionally normalized - default is normalized)
+  # @param env [Hash] A modifed Rack environment that contains a lot of context about the request
   # @param config [Hash] Endpoint configuration
   # @return [Hash] Response data
-  def call(payload:, headers:, config:)
+  def call(payload:, headers:, env:, config:)
     return {
       status: "success"
     }
@@ -123,9 +124,10 @@ class Example < Hooks::Plugins::Handlers::Base
   #
   # @param payload [Hash, String] Webhook payload
   # @param headers [Hash<String, String>] HTTP headers
+  # @param env [Hash] A modified Rack environment that contains a lot of context about the request
   # @param config [Hash] Endpoint configuration
   # @return [Hash] Response data
-  def call(payload:, headers:, config:)
+  def call(payload:, headers:, env:, config:)
     result = Retryable.with_context(:default) do
       some_operation_that_might_fail()
     end

docs/instrument_plugins.md

@@ -160,7 +160,7 @@ Once configured, your custom instruments are available throughout the applicatio
 
 ```ruby
 class MyHandler < Hooks::Plugins::Handlers::Base
-  def call(payload:, headers:, config:)
+  def call(payload:, headers:, env:, config:)
     # Use your custom stats methods
     stats.increment("handler.calls", { handler: "MyHandler" })
 

lib/hooks/app/api.rb

@@ -109,6 +109,7 @@ def self.create(config:, endpoints:, log:)
                   response = handler.call(
                     payload:,
                     headers: processed_headers,
+                    env: rack_env,
                     config: endpoint_config
                   )
 

lib/hooks/app/endpoints/catchall.rb

@@ -58,6 +58,10 @@ def self.route_block(captured_config, captured_logger)
               response = handler.call(
                 payload:,
                 headers:,
+                env: { # a very limited Rack environment is present for catchall endpoints
+                  "REQUEST_METHOD" => request.request_method,
+                  "hooks.request_id" => request_id,
+                },
                 config: {}
               )
 

lib/hooks/plugins/handlers/base.rb

@@ -16,10 +16,11 @@ class Base
         #
         # @param payload [Hash, String] Parsed request body (JSON Hash) or raw string
         # @param headers [Hash] HTTP headers (string keys, optionally normalized - default is normalized)
+        # @param env [Hash] Rack environment (contains the request context, headers, etc - very rich context)
         # @param config [Hash] Merged endpoint configuration including opts section (symbolized keys)
         # @return [Hash, String, nil] Response body (will be auto-converted to JSON)
         # @raise [NotImplementedError] if not implemented by subclass
-        def call(payload:, headers:, config:)
+        def call(payload:, headers:, env:, config:)
           raise NotImplementedError, "Handler must implement #call method"
         end
       end

lib/hooks/plugins/handlers/default.rb

@@ -20,6 +20,7 @@ class DefaultHandler < Hooks::Plugins::Handlers::Base
   #
   # @param payload [Hash, String] The webhook payload (parsed JSON or raw string)
   # @param headers [Hash<String, String>] HTTP headers from the webhook request
+  # @param env [Hash] Rack environment (contains the request context, headers, config, etc - very rich context)
   # @param config [Hash] Endpoint configuration containing handler options
   # @return [Hash] Response indicating successful processing
   # @option config [Hash] :opts Additional handler-specific configuration options
@@ -29,10 +30,11 @@ class DefaultHandler < Hooks::Plugins::Handlers::Base
   #   response = handler.call(
   #     payload: { "event" => "push" },
   #     headers: { "Content-Type" => "application/json" },
+  #     env: { "REQUEST_METHOD" => "POST", "hooks.request_id" => "12345" },
   #     config: { opts: {} }
   #   )
   #   # => { message: "webhook processed successfully", handler: "DefaultHandler", timestamp: "..." }
-  def call(payload:, headers:, config:)
+  def call(payload:, headers:, env:, config:)
 
     log.info("🔔 Default handler invoked for webhook 🔔")
 
@@ -41,6 +43,10 @@ def call(payload:, headers:, config:)
       log.debug("received payload: #{payload.inspect}")
     end
 
+    if env
+      log.debug("default handler got a request with the following request_id: #{env['hooks.request_id']}")
+    end
+
     {
       message: "webhook processed successfully",
       handler: "DefaultHandler",

spec/acceptance/plugins/handlers/boomtown.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 class Boomtown < Hooks::Plugins::Handlers::Base
-  def call(payload:, headers:, config:)
+  def call(payload:, headers:, env:, config:)
     raise StandardError, "Boomtown error occurred"
   end
 end

spec/acceptance/plugins/handlers/github_handler.rb

@@ -8,7 +8,7 @@ class GithubHandler < Hooks::Plugins::Handlers::Base
   # @param headers [Hash<String, String>] HTTP headers
   # @param config [Hash] Endpoint configuration
   # @return [Hash] Response data
-  def call(payload:, headers:, config:)
+  def call(payload:, headers:, env:, config:)
     log.info("🚀 Processing GitHub webhook 🚀")
     return {
       status: "success"