philiprehberger-webhook_builder 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f8ace17a470352fbec4b6af92b0e625b346bc6c0580c9e7a53c8ff8ea2c30260
-  data.tar.gz: c279d283cb23ac437bd9496b21788de77defe91b68027ae462d47197dd27b0b7
+  metadata.gz: 9992d034a4e76ce146dae4dfba7d503b3eb27cb2bc12722655ffa1f84a24b6ab
+  data.tar.gz: 112d676f685b96e900a9a96adcf529165a346b28c587c6d1a76ac1f1fe333fc1
 SHA512:
-  metadata.gz: 8fcc581ae60c693c6e5ddaa623fc446e80cb237cad545ae13e142c629903624395c9d189a8228056e63193c15e838c2725137914538bc9e8b1c876e9f36a0b28
-  data.tar.gz: ddddb6c9797f16e38dd7797fb4eee25bc265ea903816772b86b92e5a9fca52d50fbbf362d5491ace4368fd2b5152bae635caaeaf693f61ed18ae072408c33f12
+  metadata.gz: a4fff7580a5193f2e2260eeb6400f3dfd06173643e909e9e06a6d88960a8237a3e132ccde8a27d263215bec87e11a1966aaecf5ee8f17d0cfe422c1b45c5603f
+  data.tar.gz: 76166bc2d3ce885fc1106600864f4edfaa8b358588b00ee2982125ca7fc069a907c4a22a2babc55905180b63fef5e7de04f1e4188a9e59410e558026a5bf028b

data/CHANGELOG.md

@@ -7,6 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-03-29
+
+### Added
+- Batch delivery via `client.deliver_batch(events)` with configurable `concurrency:` option
+- Retry backoff strategies: `:exponential` (default), `:linear`, `:fixed`, or custom Proc via `backoff:` option
+- Backoff strategy classes in `Philiprehberger::WebhookBuilder::Backoff` module
+- Header customization with per-delivery `headers:` parameter and client-level `default_headers:` option
+- Per-delivery headers override default headers
+
+## [0.1.1] - 2026-03-22
+
+### Changed
+- Expand test coverage
+
 ## [0.1.0] - 2026-03-22
 
 ### Added

data/README.md

@@ -2,7 +2,12 @@
 
 [![Tests](https://github.com/philiprehberger/rb-webhook-builder/actions/workflows/ci.yml/badge.svg)](https://github.com/philiprehberger/rb-webhook-builder/actions/workflows/ci.yml)
 [![Gem Version](https://badge.fury.io/rb/philiprehberger-webhook_builder.svg)](https://rubygems.org/gems/philiprehberger-webhook_builder)
+[![GitHub release](https://img.shields.io/github/v/release/philiprehberger/rb-webhook-builder)](https://github.com/philiprehberger/rb-webhook-builder/releases)
+[![Last updated](https://img.shields.io/github/last-commit/philiprehberger/rb-webhook-builder)](https://github.com/philiprehberger/rb-webhook-builder/commits/main)
 [![License](https://img.shields.io/github/license/philiprehberger/rb-webhook-builder)](LICENSE)
+[![Bug Reports](https://img.shields.io/github/issues/philiprehberger/rb-webhook-builder/bug)](https://github.com/philiprehberger/rb-webhook-builder/issues?q=is%3Aissue+is%3Aopen+label%3Abug)
+[![Feature Requests](https://img.shields.io/github/issues/philiprehberger/rb-webhook-builder/enhancement)](https://github.com/philiprehberger/rb-webhook-builder/issues?q=is%3Aissue+is%3Aopen+label%3Aenhancement)
+[![Sponsor](https://img.shields.io/badge/sponsor-GitHub%20Sponsors-ec6cb9)](https://github.com/sponsors/philiprehberger)
 
 Webhook delivery client with HMAC signing, retry, and tracking
 
@@ -39,20 +44,91 @@ delivery.success?      # => true
 delivery.response_code # => 200
 ```
 
-### Custom Options
+### Batch Delivery
 
 ```ruby
+require "philiprehberger/webhook_builder"
+
+client = Philiprehberger::WebhookBuilder.new(
+  url: "https://example.com/webhooks",
+  secret: "your-signing-secret",
+  concurrency: 8
+)
+
+events = [
+  { event: "order.created", payload: { id: 1 } },
+  { event: "order.updated", payload: { id: 2 } },
+  { event: "order.deleted", payload: { id: 3 } }
+]
+
+results = client.deliver_batch(events)
+results.each { |d| puts "#{d.response_code}: #{d.success?}" }
+```
+
+### Backoff Strategies
+
+```ruby
+require "philiprehberger/webhook_builder"
+
+# Exponential backoff (default): 1s, 2s, 4s, 8s, ...
+client = Philiprehberger::WebhookBuilder.new(
+  url: "https://example.com/webhooks",
+  secret: "secret",
+  backoff: :exponential
+)
+
+# Linear backoff: 1s, 2s, 3s, 4s, ...
+client = Philiprehberger::WebhookBuilder.new(
+  url: "https://example.com/webhooks",
+  secret: "secret",
+  backoff: :linear
+)
+
+# Fixed backoff: 1s, 1s, 1s, ...
+client = Philiprehberger::WebhookBuilder.new(
+  url: "https://example.com/webhooks",
+  secret: "secret",
+  backoff: :fixed
+)
+
+# Custom Proc backoff
+client = Philiprehberger::WebhookBuilder.new(
+  url: "https://example.com/webhooks",
+  secret: "secret",
+  backoff: ->(attempt) { attempt * 0.5 }
+)
+```
+
+### Header Customization
+
+```ruby
+require "philiprehberger/webhook_builder"
+
+# Default headers on all deliveries
 client = Philiprehberger::WebhookBuilder.new(
-  url: "https://api.example.com/hooks",
-  secret: "hmac-secret",
-  timeout: 10,
-  max_retries: 5
+  url: "https://example.com/webhooks",
+  secret: "secret",
+  default_headers: { "X-Tenant" => "acme" }
+)
+
+# Per-delivery headers (override defaults)
+client.deliver(
+  event: "order.created",
+  payload: { id: 1 },
+  headers: { "X-Priority" => "high" }
 )
 ```
 
 ### Delivery Tracking
 
 ```ruby
+require "philiprehberger/webhook_builder"
+
+client = Philiprehberger::WebhookBuilder.new(
+  url: "https://example.com/webhooks",
+  secret: "secret"
+)
+
 delivery = client.deliver(event: "user.updated", payload: { id: 42 })
 
 delivery.success?       # => true/false
@@ -63,18 +139,15 @@ delivery.response_body  # => '{"ok":true}'
 delivery.error          # => nil or error message
 ```
 
-### HMAC Signing
-
-Every request includes an `X-Webhook-Signature` header with an HMAC-SHA256 hex digest of the JSON body, signed with the configured secret. The `X-Webhook-Event` header contains the event type.
-
 ## API
 
 ### `Client`
 
 | Method | Description |
 |--------|-------------|
-| `.new(url:, secret:, timeout:, max_retries:)` | Create a webhook client (timeout defaults to 30s, retries to 3) |
-| `#deliver(event:, payload:)` | Deliver a webhook event and return a Delivery |
+| `.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 |
 
 ### `Delivery`
 
@@ -87,6 +160,27 @@ Every request includes an `X-Webhook-Signature` header with an HMAC-SHA256 hex d
 | `#response_body` | The response body string |
 | `#error` | Error message if delivery failed |
 
+### `Backoff::Exponential`
+
+| Method | Description |
+|--------|-------------|
+| `.new(base:, max_delay:, jitter:)` | Create exponential strategy (defaults: base=1, max_delay=30, jitter=false) |
+| `#call(attempt)` | Calculate delay for given attempt |
+
+### `Backoff::Linear`
+
+| Method | Description |
+|--------|-------------|
+| `.new(base:, max_delay:)` | Create linear strategy (defaults: base=1, max_delay=30) |
+| `#call(attempt)` | Calculate delay for given attempt |
+
+### `Backoff::Fixed`
+
+| Method | Description |
+|--------|-------------|
+| `.new(delay:)` | Create fixed strategy (default: delay=1) |
+| `#call(attempt)` | Returns constant delay |
+
 ## Development
 
 ```bash
@@ -95,6 +189,13 @@ bundle exec rspec
 bundle exec rubocop
 ```
 
+## Support
+
+If you find this package useful, consider giving it a star on GitHub — it helps motivate continued maintenance and development.
+
+[![LinkedIn](https://img.shields.io/badge/Philip%20Rehberger-LinkedIn-0A66C2?logo=linkedin)](https://www.linkedin.com/in/philiprehberger)
+[![More packages](https://img.shields.io/badge/more-open%20source%20packages-blue)](https://philiprehberger.com/open-source-packages)
+
 ## License
 
-MIT
+[MIT](LICENSE)

data/lib/philiprehberger/webhook_builder/backoff.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Philiprehberger
+  module WebhookBuilder
+    module Backoff
+      # Exponential backoff: base * 2^attempt, capped at max_delay.
+      class Exponential
+        # @param base [Numeric] base delay in seconds (default: 1)
+        # @param max_delay [Numeric] maximum delay in seconds (default: 30)
+        # @param jitter [Boolean] whether to add random jitter (default: false)
+        def initialize(base: 1, max_delay: 30, jitter: false)
+          @base = base
+          @max_delay = max_delay
+          @jitter = jitter
+        end
+
+        # @param attempt [Integer] the current attempt number (1-based)
+        # @return [Float] delay in seconds
+        def call(attempt)
+          delay = [@base * (2**(attempt - 1)), @max_delay].min.to_f
+          delay *= rand if @jitter
+          delay
+        end
+      end
+
+      # Linear backoff: base * attempt, capped at max_delay.
+      class Linear
+        # @param base [Numeric] base delay in seconds (default: 1)
+        # @param max_delay [Numeric] maximum delay in seconds (default: 30)
+        def initialize(base: 1, max_delay: 30)
+          @base = base
+          @max_delay = max_delay
+        end
+
+        # @param attempt [Integer] the current attempt number (1-based)
+        # @return [Float] delay in seconds
+        def call(attempt)
+          [@base * attempt, @max_delay].min.to_f
+        end
+      end
+
+      # Fixed backoff: constant delay.
+      class Fixed
+        # @param delay [Numeric] delay in seconds (default: 1)
+        def initialize(delay: 1)
+          @delay = delay
+        end
+
+        # @param _attempt [Integer] ignored
+        # @return [Float] delay in seconds
+        def call(_attempt)
+          @delay.to_f
+        end
+      end
+
+      # Resolve a backoff option into a callable strategy.
+      #
+      # @param option [Symbol, Proc, nil] the backoff strategy
+      # @return [#call] a callable backoff strategy
+      def self.resolve(option)
+        case option
+        when :exponential, nil
+          Exponential.new
+        when :linear
+          Linear.new
+        when :fixed
+          Fixed.new
+        when Proc
+          option
+        else
+          raise ArgumentError, "Unknown backoff strategy: #{option.inspect}. Use :exponential, :linear, :fixed, or a Proc."
+        end
+      end
+    end
+  end
+end

data/lib/philiprehberger/webhook_builder/client.rb

@@ -1,10 +1,10 @@
 # frozen_string_literal: true
 
-require "net/http"
-require "uri"
-require "json"
-require "openssl"
-require "time"
+require 'net/http'
+require 'uri'
+require 'json'
+require 'openssl'
+require 'time'
 
 module Philiprehberger
   module WebhookBuilder
@@ -19,27 +19,42 @@ module Philiprehberger
       # @return [Integer] the maximum number of delivery attempts
       attr_reader :max_retries
 
+      # @return [Integer] the maximum number of concurrent batch deliveries
+      attr_reader :concurrency
+
+      # @return [Hash] default headers included in every delivery
+      attr_reader :default_headers
+
       # Create a new webhook client.
       #
       # @param url [String] the webhook endpoint URL
       # @param secret [String] the HMAC-SHA256 signing secret
       # @param timeout [Integer] HTTP timeout in seconds (default: 30)
       # @param max_retries [Integer] maximum retry attempts on failure (default: 3)
-      def initialize(url:, secret:, timeout: 30, max_retries: 3)
+      # @param backoff [Symbol, Proc] backoff strategy — :exponential (default), :linear, :fixed, or a Proc
+      # @param concurrency [Integer] maximum concurrent threads for batch delivery (default: 4)
+      # @param default_headers [Hash] headers to include in every delivery
+      def initialize(url:, secret:, timeout: 30, max_retries: 3, backoff: :exponential, concurrency: 4,
+                     default_headers: {})
         @url = url
         @secret = secret
         @timeout = timeout
         @max_retries = max_retries
+        @backoff_strategy = Backoff.resolve(backoff)
+        @concurrency = concurrency
+        @default_headers = default_headers.dup.freeze
       end
 
       # Deliver a webhook event.
       #
       # @param event [String] the event type (e.g., "order.created")
       # @param payload [Hash] the event payload
+      # @param headers [Hash] per-delivery headers (override default_headers)
       # @return [Delivery] the delivery result
-      def deliver(event:, payload:)
+      def deliver(event:, payload:, headers: {})
         body = JSON.generate({ event: event, payload: payload, timestamp: Time.now.utc.iso8601 })
         signature = sign(body)
+        merged_headers = @default_headers.merge(headers)
 
         attempts = 0
         start_time = monotonic_now
@@ -50,7 +65,7 @@ module Philiprehberger
         loop do
           attempts += 1
           begin
-            response = send_request(body, signature, event)
+            response = send_request(body, signature, event, merged_headers)
             last_response_code = response.code.to_i
             last_response_body = response.body
 
@@ -71,7 +86,7 @@ module Philiprehberger
 
           break if attempts > @max_retries
 
-          sleep(backoff_delay(attempts))
+          sleep(@backoff_strategy.call(attempts))
         end
 
         Delivery.new(
@@ -84,6 +99,44 @@ module Philiprehberger
         )
       end
 
+      # Deliver multiple webhook events concurrently.
+      #
+      # @param events [Array<Hash>] array of { event:, payload: } hashes, optionally with headers:
+      # @return [Array<Delivery>] delivery results in the same order as input
+      def deliver_batch(events)
+        results = Array.new(events.length)
+        mutex = Mutex.new
+        queue = Queue.new
+
+        events.each_with_index do |item, index|
+          queue << [item, index]
+        end
+
+        threads = Array.new([@concurrency, events.length].min) do
+          Thread.new do
+            loop do
+              pair = begin
+                queue.pop(true)
+              rescue ThreadError
+                nil
+              end
+              break unless pair
+
+              item, index = pair
+              delivery = deliver(
+                event: item[:event],
+                payload: item[:payload],
+                headers: item.fetch(:headers, {})
+              )
+              mutex.synchronize { results[index] = delivery }
+            end
+          end
+        end
+
+        threads.each(&:join)
+        results
+      end
+
       private
 
       # Sign the request body with HMAC-SHA256.
@@ -91,7 +144,7 @@ module Philiprehberger
       # @param body [String] the JSON body
       # @return [String] the hex-encoded HMAC signature
       def sign(body)
-        OpenSSL::HMAC.hexdigest("SHA256", @secret, body)
+        OpenSSL::HMAC.hexdigest('SHA256', @secret, body)
       end
 
       # Send the HTTP POST request.
@@ -99,32 +152,28 @@ module Philiprehberger
       # @param body [String] the JSON body
       # @param signature [String] the HMAC signature
       # @param event [String] the event type
+      # @param extra_headers [Hash] additional headers to include
       # @return [Net::HTTPResponse]
-      def send_request(body, signature, event)
+      def send_request(body, signature, event, extra_headers = {})
         uri = URI.parse(@url)
         http = Net::HTTP.new(uri.host, uri.port)
-        http.use_ssl = uri.scheme == "https"
+        http.use_ssl = uri.scheme == 'https'
         http.open_timeout = @timeout
         http.read_timeout = @timeout
 
         request = Net::HTTP::Post.new(uri.request_uri)
-        request["Content-Type"] = "application/json"
-        request["X-Webhook-Signature"] = signature
-        request["X-Webhook-Event"] = event
-        request["User-Agent"] = "philiprehberger-webhook_builder/#{VERSION}"
+        request['Content-Type'] = 'application/json'
+        request['X-Webhook-Signature'] = signature
+        request['X-Webhook-Event'] = event
+        request['User-Agent'] = "philiprehberger-webhook_builder/#{VERSION}"
+
+        extra_headers.each { |key, value| request[key] = value }
+
         request.body = body
 
         http.request(request)
       end
 
-      # Calculate exponential backoff delay.
-      #
-      # @param attempt [Integer] the current attempt number
-      # @return [Float] delay in seconds
-      def backoff_delay(attempt)
-        [2**(attempt - 1), 30].min
-      end
-
       def monotonic_now
         Process.clock_gettime(Process::CLOCK_MONOTONIC)
       end

data/lib/philiprehberger/webhook_builder/version.rb

@@ -2,6 +2,6 @@
 
 module Philiprehberger
   module WebhookBuilder
-    VERSION = "0.1.0"
+    VERSION = '0.2.0'
   end
 end

data/lib/philiprehberger/webhook_builder.rb

@@ -15,6 +15,7 @@ module Philiprehberger
   end
 end
 
-require_relative "webhook_builder/version"
-require_relative "webhook_builder/delivery"
-require_relative "webhook_builder/client"
+require_relative 'webhook_builder/version'
+require_relative 'webhook_builder/delivery'
+require_relative 'webhook_builder/backoff'
+require_relative 'webhook_builder/client'

metadata

@@ -1,18 +1,19 @@
 --- !ruby/object:Gem::Specification
 name: philiprehberger-webhook_builder
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Philip Rehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-22 00:00:00.000000000 Z
+date: 2026-03-30 00:00:00.000000000 Z
 dependencies: []
 description: A webhook delivery client that signs payloads with HMAC-SHA256, retries
-  failed deliveries with exponential backoff, and tracks delivery status including
-  response codes, attempts, and duration.
+  failed deliveries with configurable backoff strategies, supports batch delivery,
+  custom headers, and tracks delivery status including response codes, attempts, and
+  duration.
 email:
 - me@philiprehberger.com
 executables: []
@@ -23,6 +24,7 @@ files:
 - LICENSE
 - README.md
 - lib/philiprehberger/webhook_builder.rb
+- lib/philiprehberger/webhook_builder/backoff.rb
 - lib/philiprehberger/webhook_builder/client.rb
 - lib/philiprehberger/webhook_builder/delivery.rb
 - lib/philiprehberger/webhook_builder/version.rb