philiprehberger-webhook_builder 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f8ace17a470352fbec4b6af92b0e625b346bc6c0580c9e7a53c8ff8ea2c30260
+  data.tar.gz: c279d283cb23ac437bd9496b21788de77defe91b68027ae462d47197dd27b0b7
+SHA512:
+  metadata.gz: 8fcc581ae60c693c6e5ddaa623fc446e80cb237cad545ae13e142c629903624395c9d189a8228056e63193c15e838c2725137914538bc9e8b1c876e9f36a0b28
+  data.tar.gz: ddddb6c9797f16e38dd7797fb4eee25bc265ea903816772b86b92e5a9fca52d50fbbf362d5491ace4368fd2b5152bae635caaeaf693f61ed18ae072408c33f12

data/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+All notable changes to this gem will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-03-22
+
+### Added
+- Initial release
+- Webhook client with configurable URL, secret, timeout, and max retries
+- HMAC-SHA256 payload signing
+- Automatic retry with exponential backoff on failure
+- Delivery tracking with success status, response code, attempts, and duration

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 philiprehberger
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,100 @@
+# philiprehberger-webhook_builder
+
+[![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)
+[![License](https://img.shields.io/github/license/philiprehberger/rb-webhook-builder)](LICENSE)
+
+Webhook delivery client with HMAC signing, retry, and tracking
+
+## Requirements
+
+- Ruby >= 3.1
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "philiprehberger-webhook_builder"
+```
+
+Or install directly:
+
+```bash
+gem install philiprehberger-webhook_builder
+```
+
+## Usage
+
+```ruby
+require "philiprehberger/webhook_builder"
+
+client = Philiprehberger::WebhookBuilder.new(
+  url: "https://example.com/webhooks",
+  secret: "your-signing-secret"
+)
+
+delivery = client.deliver(event: "order.created", payload: { id: 123, total: 49.99 })
+delivery.success?      # => true
+delivery.response_code # => 200
+```
+
+### Custom Options
+
+```ruby
+client = Philiprehberger::WebhookBuilder.new(
+  url: "https://api.example.com/hooks",
+  secret: "hmac-secret",
+  timeout: 10,
+  max_retries: 5
+)
+```
+
+### Delivery Tracking
+
+```ruby
+delivery = client.deliver(event: "user.updated", payload: { id: 42 })
+
+delivery.success?       # => true/false
+delivery.response_code  # => 200
+delivery.attempts       # => 1
+delivery.duration       # => 0.342 (seconds)
+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 |
+
+### `Delivery`
+
+| Method | Description |
+|--------|-------------|
+| `#success?` | Whether the delivery succeeded (2xx response) |
+| `#response_code` | The HTTP response code |
+| `#attempts` | Number of delivery attempts made |
+| `#duration` | Total duration in seconds across all attempts |
+| `#response_body` | The response body string |
+| `#error` | Error message if delivery failed |
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## License
+
+MIT

data/lib/philiprehberger/webhook_builder/client.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "json"
+require "openssl"
+require "time"
+
+module Philiprehberger
+  module WebhookBuilder
+    # Webhook delivery client with HMAC signing, retry, and tracking.
+    class Client
+      # @return [String] the webhook endpoint URL
+      attr_reader :url
+
+      # @return [Integer] the HTTP timeout in seconds
+      attr_reader :timeout
+
+      # @return [Integer] the maximum number of delivery attempts
+      attr_reader :max_retries
+
+      # 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)
+        @url = url
+        @secret = secret
+        @timeout = timeout
+        @max_retries = max_retries
+      end
+
+      # Deliver a webhook event.
+      #
+      # @param event [String] the event type (e.g., "order.created")
+      # @param payload [Hash] the event payload
+      # @return [Delivery] the delivery result
+      def deliver(event:, payload:)
+        body = JSON.generate({ event: event, payload: payload, timestamp: Time.now.utc.iso8601 })
+        signature = sign(body)
+
+        attempts = 0
+        start_time = monotonic_now
+        last_response_code = nil
+        last_response_body = nil
+        last_error = nil
+
+        loop do
+          attempts += 1
+          begin
+            response = send_request(body, signature, event)
+            last_response_code = response.code.to_i
+            last_response_body = response.body
+
+            if last_response_code >= 200 && last_response_code < 300
+              return Delivery.new(
+                success: true,
+                response_code: last_response_code,
+                attempts: attempts,
+                duration: monotonic_now - start_time,
+                response_body: last_response_body
+              )
+            end
+
+            last_error = "HTTP #{last_response_code}"
+          rescue StandardError => e
+            last_error = e.message
+          end
+
+          break if attempts > @max_retries
+
+          sleep(backoff_delay(attempts))
+        end
+
+        Delivery.new(
+          success: false,
+          response_code: last_response_code,
+          attempts: attempts,
+          duration: monotonic_now - start_time,
+          response_body: last_response_body,
+          error: last_error
+        )
+      end
+
+      private
+
+      # Sign the request body with HMAC-SHA256.
+      #
+      # @param body [String] the JSON body
+      # @return [String] the hex-encoded HMAC signature
+      def sign(body)
+        OpenSSL::HMAC.hexdigest("SHA256", @secret, body)
+      end
+
+      # Send the HTTP POST request.
+      #
+      # @param body [String] the JSON body
+      # @param signature [String] the HMAC signature
+      # @param event [String] the event type
+      # @return [Net::HTTPResponse]
+      def send_request(body, signature, event)
+        uri = URI.parse(@url)
+        http = Net::HTTP.new(uri.host, uri.port)
+        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.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
+    end
+  end
+end

data/lib/philiprehberger/webhook_builder/delivery.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Philiprehberger
+  module WebhookBuilder
+    # Represents the result of a webhook delivery attempt.
+    class Delivery
+      # @return [Boolean] whether the delivery succeeded (2xx response)
+      attr_reader :success
+
+      # @return [Integer, nil] the HTTP response code
+      attr_reader :response_code
+
+      # @return [Integer] the number of delivery attempts made
+      attr_reader :attempts
+
+      # @return [Float] the total duration in seconds across all attempts
+      attr_reader :duration
+
+      # @return [String, nil] the response body
+      attr_reader :response_body
+
+      # @return [String, nil] the error message if delivery failed
+      attr_reader :error
+
+      # @param success [Boolean]
+      # @param response_code [Integer, nil]
+      # @param attempts [Integer]
+      # @param duration [Float]
+      # @param response_body [String, nil]
+      # @param error [String, nil]
+      def initialize(success:, response_code:, attempts:, duration:, response_body: nil, error: nil)
+        @success = success
+        @response_code = response_code
+        @attempts = attempts
+        @duration = duration
+        @response_body = response_body
+        @error = error
+      end
+
+      # Whether the delivery was successful.
+      #
+      # @return [Boolean]
+      def success?
+        @success
+      end
+    end
+  end
+end

data/lib/philiprehberger/webhook_builder/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Philiprehberger
+  module WebhookBuilder
+    VERSION = "0.1.0"
+  end
+end

data/lib/philiprehberger/webhook_builder.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Philiprehberger
+  module WebhookBuilder
+    class Error < StandardError; end
+
+    # Convenience method to create a new webhook client.
+    #
+    # @param options [Hash] options passed to {Client#initialize}
+    # @return [Client] a new webhook client
+    # @see Client#initialize
+    def self.new(**options)
+      Client.new(**options)
+    end
+  end
+end
+
+require_relative "webhook_builder/version"
+require_relative "webhook_builder/delivery"
+require_relative "webhook_builder/client"

metadata

@@ -0,0 +1,57 @@
+--- !ruby/object:Gem::Specification
+name: philiprehberger-webhook_builder
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Philip Rehberger
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-03-22 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.
+email:
+- me@philiprehberger.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/philiprehberger/webhook_builder.rb
+- lib/philiprehberger/webhook_builder/client.rb
+- lib/philiprehberger/webhook_builder/delivery.rb
+- lib/philiprehberger/webhook_builder/version.rb
+homepage: https://github.com/philiprehberger/rb-webhook-builder
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/philiprehberger/rb-webhook-builder
+  source_code_uri: https://github.com/philiprehberger/rb-webhook-builder
+  changelog_uri: https://github.com/philiprehberger/rb-webhook-builder/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/philiprehberger/rb-webhook-builder/issues
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Webhook delivery client with HMAC signing, retry, and tracking
+test_files: []