philiprehberger-webhook_builder 0.2.2 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dc97be824aada00ec5793cb30aedac642f075494d8e5d73410995d65270a60f0
-  data.tar.gz: 79ff8ead44f6bdb0493eb6af38b145ad9d5a44ff6eec49d41aec49d2d24d66f7
+  metadata.gz: 7754a65fd17d3f711872d837db0a95670d245eab1da96df4d42c723b8d7f9f3d
+  data.tar.gz: 8be04c1b22974980e572ca5073279d995f6e8f67d8853742de62297e5951a532
 SHA512:
-  metadata.gz: 020aaf34af4930b84e913fe0fcb23100cd9aa10a9e0b7cc8d50bd1dd2e4e5a7531e327bf28879bca64a5961adb1709839ff767e75d60051b48a815b11b37448e
-  data.tar.gz: 657d920700388d52e2512d1b5d4de25e0c17a6266041f468857f41628f68fe024844d41892a72224f4632422ba7d2e7237b4703d8dacc19c0cc40236d80f2311
+  metadata.gz: 5f756201c37028a4f44d5975200d24fb811d87ecbc13467b9a9f3e5c792333c26dc546177871b9bda42d4bef3da1093202aa5f82279622521bf5c443d4fe61f8
+  data.tar.gz: c09e9a31e51d343140eb0beaa1db83560bd7a35dca976f00332534a888ece0eb8263a9701a6b5bf14720388ad381245b44b089689700fa0298ff9a5b16130742

data/CHANGELOG.md

@@ -7,6 +7,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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,26 @@ 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
+```
+
 ### Delivery Tracking
 
 ```ruby
@@ -143,6 +163,7 @@ 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 |
 
 ### `Delivery`
 

data/lib/philiprehberger/webhook_builder/client.rb

@@ -137,6 +137,22 @@ 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
+
       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.3.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.3.0
 platform: ruby
 authors:
 - Philip Rehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-15 00:00:00.000000000 Z
+date: 2026-04-19 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,