philiprehberger-webhook_builder 0.2.2 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dc97be824aada00ec5793cb30aedac642f075494d8e5d73410995d65270a60f0
-  data.tar.gz: 79ff8ead44f6bdb0493eb6af38b145ad9d5a44ff6eec49d41aec49d2d24d66f7
+  metadata.gz: 5c3d746e099083b6d9da206ce5b4630ca0a4c5ee2c4f1f99373af3c992d89c38
+  data.tar.gz: 23ed5e8d7b8e40f27a71cf7f4cb42c91d501ef8a5028d39d0a77cd1d08a589be
 SHA512:
-  metadata.gz: 020aaf34af4930b84e913fe0fcb23100cd9aa10a9e0b7cc8d50bd1dd2e4e5a7531e327bf28879bca64a5961adb1709839ff767e75d60051b48a815b11b37448e
-  data.tar.gz: 657d920700388d52e2512d1b5d4de25e0c17a6266041f468857f41628f68fe024844d41892a72224f4632422ba7d2e7237b4703d8dacc19c0cc40236d80f2311
+  metadata.gz: 7e503cd54a9fb91a78879f0ccd541a24b91a447ca30ba89c7d832a4c757d07de2a35e7c0066c8c0e13c01b130f6765afdc96b4b8e234c4ba60d492aba2d3e536
+  data.tar.gz: 6f9942dc1678940173ab109c17b236f83bf14087ed1dae8880f17a2703e8e89a87c2455e752ea7c9b6aff14f6992bd408db65bd46b0499729ec8644d27e7d561

data/CHANGELOG.md

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-04-22
+
+### Added
+- `Client#signature_for(body:)` — compute the HMAC-SHA256 signature this client would send for a given body without performing a delivery.
+
+## [0.3.0] - 2026-04-18
+
+### Added
+- `Client#verify_signature(body:, signature:)` — constant-time HMAC-SHA256 comparison for the receiving side; returns `false` (never raises) on length mismatch
+
 ## [0.2.2] - 2026-04-15
 
 ### Changed

data/README.md

@@ -114,6 +114,44 @@ client.deliver(
 )
 ```
 
+### Verifying signatures
+
+On the receiving side, use the same secret to verify the signature sent in the
+`X-Webhook-Signature` header. The comparison is constant-time and will never
+raise on malformed input.
+
+```ruby
+require "philiprehberger/webhook_builder"
+
+secret = "shared-signing-secret"
+sender = Philiprehberger::WebhookBuilder.new(url: "https://example.com/webhooks", secret: secret)
+receiver = Philiprehberger::WebhookBuilder.new(url: "https://example.com/webhooks", secret: secret)
+
+body = '{"event":"order.created","payload":{"id":1}}'
+signature = OpenSSL::HMAC.hexdigest("SHA256", secret, body)
+
+receiver.verify_signature(body: body, signature: signature) # => true
+receiver.verify_signature(body: body, signature: "tampered") # => false
+```
+
+You can also compute the signature the client would send for a body without
+performing a delivery — useful for preparing payloads offline or mirroring
+`verify_signature`:
+
+```ruby
+require "philiprehberger/webhook_builder"
+
+client = Philiprehberger::WebhookBuilder.new(
+  url: "https://example.com/webhooks",
+  secret: "shared-signing-secret"
+)
+
+body = '{"event":"order.created","payload":{"id":1}}'
+signature = client.signature_for(body: body)
+
+client.verify_signature(body: body, signature: signature) # => true
+```
+
 ### Delivery Tracking
 
 ```ruby
@@ -143,6 +181,8 @@ delivery.error          # => nil or error message
 | `.new(url:, secret:, timeout:, max_retries:, backoff:, concurrency:, default_headers:)` | Create a webhook client |
 | `#deliver(event:, payload:, headers:)` | Deliver a webhook event and return a Delivery |
 | `#deliver_batch(events)` | Deliver multiple events concurrently and return an array of Delivery results |
+| `#verify_signature(body:, signature:)` | Constant-time HMAC-SHA256 verification of an incoming signature; returns `true`/`false` and never raises |
+| `#signature_for(body:)` | Compute the HMAC-SHA256 signature for a body without sending |
 
 ### `Delivery`
 

data/lib/philiprehberger/webhook_builder/client.rb

@@ -137,6 +137,34 @@ module Philiprehberger
         results
       end
 
+      # Verify an HMAC-SHA256 signature against a raw request body.
+      #
+      # Uses a constant-time comparison to resist timing attacks. Returns
+      # +false+ (never raises) when the provided signature has a different
+      # length than the expected hex digest.
+      #
+      # @param body [String] the raw request body
+      # @param signature [String] the hex-encoded signature to verify
+      # @return [Boolean] true when the signature matches, false otherwise
+      def verify_signature(body:, signature:)
+        expected = sign(body)
+        return false unless signature.is_a?(String) && signature.bytesize == expected.bytesize
+
+        OpenSSL.fixed_length_secure_compare(expected, signature)
+      end
+
+      # Compute the HMAC-SHA256 hex signature this client would send for the given body.
+      #
+      # Mirrors +verify_signature+: the signature returned by +signature_for(body:)+
+      # will verify against the same body. Useful when preparing payloads offline or
+      # re-computing signatures without sending a request.
+      #
+      # @param body [String] the raw request body
+      # @return [String] the hex-encoded HMAC signature
+      def signature_for(body:)
+        sign(body)
+      end
+
       private
 
       # Sign the request body with HMAC-SHA256.

data/lib/philiprehberger/webhook_builder/version.rb

@@ -2,6 +2,6 @@
 
 module Philiprehberger
   module WebhookBuilder
-    VERSION = '0.2.2'
+    VERSION = '0.4.0'
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: philiprehberger-webhook_builder
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.4.0
 platform: ruby
 authors:
 - Philip Rehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-15 00:00:00.000000000 Z
+date: 2026-04-22 00:00:00.000000000 Z
 dependencies: []
 description: A webhook delivery client that signs payloads with HMAC-SHA256, retries
   failed deliveries with configurable backoff strategies, supports batch delivery,