rails_webhook_outbox 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 743d24ea18d5fad259efd9369fc228866eeb883e6f5911d96d081e304a62aca4
+  data.tar.gz: 9bd087f6a44e6eedb95b1ccd97fd9e52423c547f67f3d4d384eb5b407fdfee1e
+SHA512:
+  metadata.gz: 02b57c5bfb462a475dde3036a6ee5f18fe033faaaa808d03d1bd45417f687162210ad6987aee0135775a5d2298fa989d65ac24c06762201cffcad05bb66938f8
+  data.tar.gz: 5fdaac46aa8ad0591e5c0837df73d9d6bd10a9af15f02f96415ac45ced02e85608198bc8beed2baaa42449e93986ac3a816b9da0e66ae8ff5ff636c2c6807a1a

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright Chuck Smith
+
+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,349 @@
+# RailsWebhookOutbox
+
+[![CI](https://github.com/eclectic-coding/rails_webhook_outbox/actions/workflows/main.yml/badge.svg)](https://github.com/eclectic-coding/rails_webhook_outbox/actions/workflows/main.yml)
+[![Gem Version](https://img.shields.io/gem/v/rails_webhook_outbox)](https://rubygems.org/gems/rails_webhook_outbox)
+[![Gem Downloads](https://img.shields.io/gem/dt/rails_webhook_outbox)](https://rubygems.org/gems/rails_webhook_outbox)
+[![Ruby](https://img.shields.io/badge/ruby-%3E%3D%203.3-red)](https://www.ruby-lang.org)
+[![Rails](https://img.shields.io/badge/rails-%3E%3D%207.2-red)](https://rubyonrails.org)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Codecov](https://codecov.io/gh/eclectic-coding/rails_webhook_outbox/graph/badge.svg)](https://codecov.io/gh/eclectic-coding/rails_webhook_outbox)
+
+A Rails engine for sending outgoing webhooks with HMAC signing, ActiveJob-based retry, and delivery logging.
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Configuration](#configuration)
+- [Subscriptions](#subscriptions)
+- [Deliveries](#deliveries)
+- [Async Delivery](#async-delivery)
+- [HTTP Request Format](#http-request-format)
+- [HMAC Signing](#hmac-signing)
+- [Usage](#usage)
+- [Manual Dispatch](#manual-dispatch)
+- [Development](#development)
+  - [Dummy App](#dummy-app)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "rails_webhook_outbox"
+```
+
+And then execute:
+
+```bash
+$ bundle install
+```
+
+Run the install generator:
+
+```bash
+$ rails generate rails_webhook_outbox:install
+$ rails db:migrate
+```
+
+## Configuration
+
+```ruby
+# config/initializers/rails_webhook_outbox.rb
+RailsWebhookOutbox.configure do |config|
+  config.events = %w[
+    order.created
+    order.updated
+    user.signed_up
+  ]
+
+  config.signing_algorithm  = :sha256
+  config.signing_header     = "X-Webhook-Signature"
+  config.max_retries        = 8
+  config.retry_backoff      = :exponential
+  config.request_timeout    = 5
+  config.delivery_job_queue = :webhooks
+end
+```
+
+[Back to top](#table-of-contents)
+
+## Subscriptions
+
+A `RailsWebhookOutbox::Subscription` represents an endpoint that receives webhook events.
+
+```ruby
+sub = RailsWebhookOutbox::Subscription.create!(
+  url: "https://example.com/webhooks",
+  events: ["order.created", "order.updated"]
+)
+
+sub.secret          # => "a3f9..." (auto-generated 64-char hex string)
+sub.active?         # => true (default)
+sub.subscribes_to?("order.created")  # => true
+sub.subscribes_to?("payment.failed") # => false
+```
+
+Use the `active` scope to find enabled subscriptions:
+
+```ruby
+RailsWebhookOutbox::Subscription.active
+```
+
+Disable a subscription by setting `active: false`:
+
+```ruby
+sub.update!(active: false)
+```
+
+[Back to top](#table-of-contents)
+
+## Deliveries
+
+A `RailsWebhookOutbox::Delivery` records each attempt to send a webhook event to a subscription endpoint.
+
+```ruby
+delivery = RailsWebhookOutbox::Delivery.create!(
+  subscription: subscription,
+  event: "order.created",
+  payload: { id: 42, total: "99.00" }
+)
+
+delivery.pending?    # => true (default)
+delivery.delivered!
+delivery.delivered?  # => true
+```
+
+Filter deliveries by status:
+
+```ruby
+RailsWebhookOutbox::Delivery.retryable   # pending — awaiting delivery or retry
+RailsWebhookOutbox::Delivery.delivered   # successfully delivered
+RailsWebhookOutbox::Delivery.failed      # exhausted all retries
+```
+
+[Back to top](#table-of-contents)
+
+## Async Delivery
+
+`RailsWebhookOutbox::DeliveryJob` handles HTTP dispatch for each `Delivery` record. It is an `ActiveJob` subclass, so it works with any queue backend (Sidekiq, Solid Queue, GoodJob, etc.).
+
+Configure the queue and retry behaviour in the initializer:
+
+```ruby
+RailsWebhookOutbox.configure do |config|
+  config.delivery_job_queue = :webhooks  # default
+  config.max_retries        = 8          # default
+end
+```
+
+The job uses polynomial backoff (`:polynomially_longer`) between retries — wait time grows with each attempt. On each failed attempt it updates the delivery record before re-raising so progress is always persisted:
+
+| Execution | Outcome | Delivery status |
+|-----------|---------|-----------------|
+| 1–(n-1) | non-2xx response | `pending` — will retry |
+| n (`max_retries`) | non-2xx response | `failed` — no further retry |
+| any | 2xx response | `delivered` |
+
+Every attempt (success or failure) increments `delivery.attempts` and stores the `response_code` and `response_body`. Successful deliveries also set `delivered_at`.
+
+Enqueue a delivery manually:
+
+```ruby
+RailsWebhookOutbox::DeliveryJob.perform_later(delivery)
+```
+
+[Back to top](#table-of-contents)
+
+## HTTP Request Format
+
+Each webhook delivery is an HTTP POST to the subscription URL with the following headers and body:
+
+```
+POST https://example.com/webhooks
+Content-Type: application/json
+X-Webhook-Signature: sha256=a1b2c3d4...
+X-Webhook-Event: order.created
+X-Webhook-Delivery: 550e8400-e29b-41d4-a716-446655440000
+X-Webhook-Timestamp: 1719100800
+
+{
+  "event": "order.created",
+  "delivered_at": "2026-06-26T10:00:00Z",
+  "data": { "id": 42, "total": "99.00" }
+}
+```
+
+Non-2xx responses raise `RailsWebhookOutbox::DeliveryError`, which carries `response_code` and `response_body` for logging and retry decisions.
+
+[Back to top](#table-of-contents)
+
+## HMAC Signing
+
+Every outgoing request includes an `X-Webhook-Signature` header (configurable) containing an HMAC digest of the request body:
+
+```
+X-Webhook-Signature: sha256=a1b2c3d4...
+```
+
+Subscribers can verify the signature:
+
+```ruby
+expected = RailsWebhookOutbox::Signature.header_value(raw_body, subscription.secret)
+Rack::Utils.secure_compare(expected, request.headers["X-Webhook-Signature"])
+```
+
+You can also call the primitives directly:
+
+```ruby
+# Produce a hex digest with an explicit algorithm
+RailsWebhookOutbox::Signature.sign(payload, secret, :sha256)
+# => "a1b2c3d4..."
+
+# Produce the full header value using the configured algorithm
+RailsWebhookOutbox::Signature.header_value(payload, secret)
+# => "sha256=a1b2c3d4..."
+```
+
+[Back to top](#table-of-contents)
+
+## Usage
+
+Include `RailsWebhookOutbox::Dispatchable` in any ActiveRecord model to automatically dispatch webhooks on lifecycle events:
+
+```ruby
+class Order < ApplicationRecord
+  include RailsWebhookOutbox::Dispatchable
+
+  dispatches_webhook "order.created", on: :create
+  dispatches_webhook "order.updated", on: :update
+  dispatches_webhook "order.cancelled", on: :update,
+    if: -> { cancelled_at_previously_changed? }
+end
+```
+
+When a callback fires, the concern finds every active `Subscription` that includes that event, creates a `Delivery` record for each one, and enqueues a `DeliveryJob`. No other wiring is required.
+
+The `if:` option accepts a lambda that is evaluated in the context of the model instance, so any attribute or method is available.
+
+**Payload**
+
+By default the full record is sent as the webhook payload via `as_json`. Override `webhook_payload` to control exactly what is sent:
+
+```ruby
+class Order < ApplicationRecord
+  include RailsWebhookOutbox::Dispatchable
+
+  dispatches_webhook "order.created", on: :create
+
+  def webhook_payload
+    { id:, total: total.to_s, items: line_items.count }
+  end
+end
+```
+
+[Back to top](#table-of-contents)
+
+## Manual Dispatch
+
+Dispatch a webhook event outside of model callbacks using `RailsWebhookOutbox.dispatch`:
+
+```ruby
+RailsWebhookOutbox.dispatch("payment.completed", {
+  id: payment.id,
+  amount: payment.amount,
+  currency: payment.currency
+})
+```
+
+`dispatch` finds every active `Subscription` that includes the given event, creates a `Delivery` record for each one, and enqueues a `DeliveryJob`. Subscriptions that are inactive or do not subscribe to the event are skipped silently.
+
+This is the same delivery pipeline used by `Dispatchable` callbacks, so retries, HMAC signing, and delivery logging all apply.
+
+[Back to top](#table-of-contents)
+
+## Development
+
+```bash
+$ bundle install
+$ bundle exec rspec
+$ bin/rubocop
+```
+
+### Dummy App
+
+The gem includes a full dummy Rails app at `spec/dummy/` for end-to-end testing in a running server. It has an `Order` model wired to `Dispatchable`, an `OrdersController`, and seed data.
+
+**Setup**
+
+From the repo root:
+
+```bash
+$ cd spec/dummy
+$ bin/setup          # installs deps, runs db:prepare, then starts the server
+```
+
+Or set up without starting the server:
+
+```bash
+$ bin/rails db:create db:migrate
+$ bin/rails db:schema:load:queue
+$ bin/rails db:seed
+```
+
+**Start the server**
+
+`bin/dev` runs the web server and solid_queue worker together via foreman:
+
+```bash
+$ bin/dev
+```
+
+The API is available at `http://localhost:3000`.
+
+**Try it with curl**
+
+Create an order (fires `order.created`):
+
+```bash
+curl -X POST http://localhost:3000/orders \
+  -H "Content-Type: application/json" \
+  -d '{"order": {"title": "Widget Pack", "total": "49.99", "status": "pending"}}'
+```
+
+Update an order (fires `order.updated`):
+
+```bash
+curl -X PATCH http://localhost:3000/orders/1 \
+  -H "Content-Type: application/json" \
+  -d '{"order": {"status": "confirmed"}}'
+```
+
+Cancel an order (fires `order.cancelled`):
+
+```bash
+curl -X PATCH http://localhost:3000/orders/1 \
+  -H "Content-Type: application/json" \
+  -d '{"order": {"status": "cancelled", "cancelled_at": "2026-06-29T12:00:00Z"}}'
+```
+
+The seed data creates a subscription pointing to `http://localhost:4000/webhooks`. Point it at any local receiver (e.g. a `webhook.site` URL or a local listener) by updating the subscription record directly:
+
+```ruby
+RailsWebhookOutbox::Subscription.first.update!(url: "https://webhook.site/your-id")
+```
+
+[Back to top](#table-of-contents)
+
+## Contributing
+
+Bug reports and pull requests are welcome on [GitHub](https://github.com/eclectic-coding/rails_webhook_outbox).
+
+[Back to top](#table-of-contents)
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+[Back to top](#table-of-contents)

data/Rakefile

@@ -0,0 +1,16 @@
+require "bundler/setup"
+
+APP_RAKEFILE = File.expand_path("spec/dummy/Rakefile", __dir__)
+load "rails/tasks/engine.rake"
+
+require "bundler/gem_tasks"
+
+require 'rubocop/rake_task'
+require 'bundler/audit/task'
+require 'rspec/core/rake_task'
+
+RuboCop::RakeTask.new(:lint)
+Bundler::Audit::Task.new
+RSpec::Core::RakeTask.new(:spec)
+
+task default: [:lint, :'bundle:audit:update', 'bundle:audit:check', :spec]

data/app/controllers/rails_webhook_outbox/application_controller.rb

@@ -0,0 +1,4 @@
+module RailsWebhookOutbox
+  class ApplicationController < ActionController::API
+  end
+end

data/app/jobs/rails_webhook_outbox/application_job.rb

@@ -0,0 +1,4 @@
+module RailsWebhookOutbox
+  class ApplicationJob < ActiveJob::Base
+  end
+end

data/app/jobs/rails_webhook_outbox/delivery_job.rb

@@ -0,0 +1,26 @@
+module RailsWebhookOutbox
+  class DeliveryJob < ApplicationJob
+    queue_as { RailsWebhookOutbox.config.delivery_job_queue }
+    retry_on RailsWebhookOutbox::DeliveryError, wait: :polynomially_longer, attempts: :unlimited
+
+    def perform(delivery)
+      response = Sender.call(delivery)
+      delivery.update!(
+        status: :delivered,
+        response_code: response.code.to_i,
+        response_body: response.body.truncate(1000),
+        delivered_at: Time.current,
+        attempts: delivery.attempts + 1
+      )
+    rescue DeliveryError => e
+      max_retries = RailsWebhookOutbox.config.max_retries
+      delivery.update!(
+        response_code: e.response_code,
+        response_body: e.response_body&.truncate(1000),
+        attempts: delivery.attempts + 1,
+        status: executions >= max_retries ? :failed : :pending
+      )
+      raise if executions < max_retries
+    end
+  end
+end

data/app/mailers/rails_webhook_outbox/application_mailer.rb

@@ -0,0 +1,6 @@
+module RailsWebhookOutbox
+  class ApplicationMailer < ActionMailer::Base
+    default from: "from@example.com"
+    layout "mailer"
+  end
+end

data/app/models/rails_webhook_outbox/application_record.rb

@@ -0,0 +1,5 @@
+module RailsWebhookOutbox
+  class ApplicationRecord < ActiveRecord::Base
+    self.abstract_class = true
+  end
+end

data/app/models/rails_webhook_outbox/delivery.rb

@@ -0,0 +1,14 @@
+module RailsWebhookOutbox
+  class Delivery < ApplicationRecord
+    self.table_name = "webhook_outbox_deliveries"
+
+    belongs_to :subscription
+
+    enum :status, { pending: 0, delivered: 1, failed: 2 }
+
+    validates :event, presence: true
+    validates :payload, presence: true
+
+    scope :retryable, -> { pending }
+  end
+end

data/app/models/rails_webhook_outbox/subscription.rb

@@ -0,0 +1,27 @@
+module RailsWebhookOutbox
+  class Subscription < ApplicationRecord
+    self.table_name = "webhook_outbox_subscriptions"
+
+    URL_FORMAT = /\Ahttps?:\/\/.+/i
+
+    attribute :active, :boolean, default: true
+
+    before_validation :generate_secret, on: :create
+
+    validates :url, presence: true, format: { with: URL_FORMAT, message: "must be a valid HTTP or HTTPS URL" }
+    validates :secret, presence: true
+    validates :events, presence: true
+
+    scope :active, -> { where(active: true) }
+
+    def subscribes_to?(event)
+      events.include?(event.to_s)
+    end
+
+    private
+
+    def generate_secret
+      self.secret ||= SecureRandom.hex(32)
+    end
+  end
+end

data/config/routes.rb

@@ -0,0 +1,2 @@
+RailsWebhookOutbox::Engine.routes.draw do
+end

data/db/migrate/20260624000001_create_webhook_outbox_subscriptions.rb

@@ -0,0 +1,13 @@
+class CreateWebhookOutboxSubscriptions < ActiveRecord::Migration[7.2]
+  def change
+    create_table :webhook_outbox_subscriptions do |t|
+      t.string :url, null: false
+      t.string :secret, null: false
+      t.json :events, null: false, default: []
+      t.boolean :active, null: false, default: true
+      t.string :description
+      t.json :metadata, default: {}
+      t.timestamps
+    end
+  end
+end

data/db/migrate/20260624000002_create_webhook_outbox_deliveries.rb

@@ -0,0 +1,20 @@
+class CreateWebhookOutboxDeliveries < ActiveRecord::Migration[7.2]
+  def change
+    create_table :webhook_outbox_deliveries do |t|
+      t.references :subscription, null: false, foreign_key: { to_table: :webhook_outbox_subscriptions }
+      t.string :event, null: false
+      t.json :payload, null: false
+      t.integer :status, null: false, default: 0
+      t.integer :response_code
+      t.text :response_body
+      t.integer :attempts, null: false, default: 0
+      t.datetime :delivered_at
+      t.datetime :next_retry_at
+      t.timestamps
+    end
+
+    add_index :webhook_outbox_deliveries, :status
+    add_index :webhook_outbox_deliveries, :event
+    add_index :webhook_outbox_deliveries, [:subscription_id, :created_at]
+  end
+end

data/lib/generators/rails_webhook_outbox/install/install_generator.rb

@@ -0,0 +1,33 @@
+require "rails/generators"
+require "rails/generators/active_record"
+
+module RailsWebhookOutbox
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      include Rails::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates a RailsWebhookOutbox initializer and copies migrations to your application."
+
+      def self.next_migration_number(dirname)
+        ActiveRecord::Generators::Base.next_migration_number(dirname)
+      end
+
+      def copy_migrations
+        migration_template(
+          "create_webhook_outbox_subscriptions.rb",
+          "db/migrate/create_webhook_outbox_subscriptions.rb"
+        )
+        migration_template(
+          "create_webhook_outbox_deliveries.rb",
+          "db/migrate/create_webhook_outbox_deliveries.rb"
+        )
+      end
+
+      def create_initializer
+        template "initializer.rb", "config/initializers/rails_webhook_outbox.rb"
+      end
+    end
+  end
+end

data/lib/generators/rails_webhook_outbox/install/templates/create_webhook_outbox_deliveries.rb

@@ -0,0 +1,20 @@
+class CreateWebhookOutboxDeliveries < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+    create_table :webhook_outbox_deliveries do |t|
+      t.references :subscription, null: false, foreign_key: { to_table: :webhook_outbox_subscriptions }
+      t.string :event, null: false
+      t.json :payload, null: false
+      t.integer :status, null: false, default: 0
+      t.integer :response_code
+      t.text :response_body
+      t.integer :attempts, null: false, default: 0
+      t.datetime :delivered_at
+      t.datetime :next_retry_at
+      t.timestamps
+    end
+
+    add_index :webhook_outbox_deliveries, :status
+    add_index :webhook_outbox_deliveries, :event
+    add_index :webhook_outbox_deliveries, [:subscription_id, :created_at]
+  end
+end

data/lib/generators/rails_webhook_outbox/install/templates/create_webhook_outbox_subscriptions.rb

@@ -0,0 +1,13 @@
+class CreateWebhookOutboxSubscriptions < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+    create_table :webhook_outbox_subscriptions do |t|
+      t.string :url, null: false
+      t.string :secret, null: false
+      t.json :events, null: false, default: []
+      t.boolean :active, null: false, default: true
+      t.string :description
+      t.json :metadata, default: {}
+      t.timestamps
+    end
+  end
+end

data/lib/generators/rails_webhook_outbox/install/templates/initializer.rb

@@ -0,0 +1,22 @@
+RailsWebhookOutbox.configure do |config|
+  # Events that subscribers can register for.
+  config.events = %w[order.created order.updated]
+
+  # HMAC algorithm for signing payloads. Options: :sha256, :sha384, :sha512
+  config.signing_algorithm = :sha256
+
+  # HTTP header that carries the HMAC signature.
+  config.signing_header = "X-Webhook-Signature"
+
+  # Maximum delivery attempts before a delivery is marked failed.
+  config.max_retries = 8
+
+  # Retry delay strategy. Options: :exponential, :linear
+  config.retry_backoff = :exponential
+
+  # HTTP timeout in seconds for each delivery attempt.
+  config.request_timeout = 5
+
+  # ActiveJob queue for delivery jobs.
+  config.delivery_job_queue = :webhooks
+end

data/lib/rails_webhook_outbox/configuration.rb

@@ -0,0 +1,38 @@
+module RailsWebhookOutbox
+  class Configuration
+    SIGNING_ALGORITHMS = %i[sha256 sha384 sha512].freeze
+    RETRY_BACKOFF_STRATEGIES = %i[exponential linear].freeze
+
+    attr_accessor :events, :signing_algorithm, :signing_header,
+                  :max_retries, :retry_backoff, :request_timeout,
+                  :delivery_job_queue
+
+    def initialize
+      @events = []
+      @signing_algorithm = :sha256
+      @signing_header = "X-Webhook-Signature"
+      @max_retries = 8
+      @retry_backoff = :exponential
+      @request_timeout = 5
+      @delivery_job_queue = :webhooks
+    end
+
+    def signing_algorithm=(value)
+      value = value.to_sym
+      unless SIGNING_ALGORITHMS.include?(value)
+        raise ArgumentError, "Unknown signing algorithm: #{value}. Must be one of: #{SIGNING_ALGORITHMS.join(", ")}"
+      end
+
+      @signing_algorithm = value
+    end
+
+    def retry_backoff=(value)
+      value = value.to_sym
+      unless RETRY_BACKOFF_STRATEGIES.include?(value)
+        raise ArgumentError, "Unknown retry backoff strategy: #{value}. Must be one of: #{RETRY_BACKOFF_STRATEGIES.join(", ")}"
+      end
+
+      @retry_backoff = value
+    end
+  end
+end

data/lib/rails_webhook_outbox/delivery_error.rb

@@ -0,0 +1,11 @@
+module RailsWebhookOutbox
+  class DeliveryError < StandardError
+    attr_reader :response_code, :response_body
+
+    def initialize(response)
+      @response_code = response.code.to_i
+      @response_body = response.body
+      super("HTTP #{@response_code}")
+    end
+  end
+end

data/lib/rails_webhook_outbox/dispatchable.rb

@@ -0,0 +1,42 @@
+module RailsWebhookOutbox
+  module Dispatchable
+    extend ActiveSupport::Concern
+
+    included do
+      class_attribute :_webhook_dispatches, instance_writer: false
+      self._webhook_dispatches = []
+    end
+
+    class_methods do
+      def dispatches_webhook(event, on:, **options)
+        condition = options[:if]
+        self._webhook_dispatches = _webhook_dispatches + [{ event: event, on: on, condition: condition }]
+        send(:"after_#{on}", -> { _dispatch_webhook(event, condition) })
+      end
+    end
+
+    def webhook_payload
+      as_json
+    end
+
+    private
+
+    def _dispatch_webhook(event, condition)
+      return if condition && !instance_exec(&condition)
+
+      payload = webhook_payload
+
+      Subscription.active.each do |subscription|
+        next unless subscription.subscribes_to?(event)
+
+        delivery = Delivery.create!(
+          subscription: subscription,
+          event: event,
+          payload: payload
+        )
+
+        DeliveryJob.perform_later(delivery)
+      end
+    end
+  end
+end

data/lib/rails_webhook_outbox/engine.rb

@@ -0,0 +1,14 @@
+module RailsWebhookOutbox
+  class Engine < ::Rails::Engine
+    isolate_namespace RailsWebhookOutbox
+    config.generators.api_only = true
+
+    initializer :append_migrations do |app|
+      unless app.root.to_s.match?(__dir__)
+        RailsWebhookOutbox::Engine.config.paths["db/migrate"].expanded.each do |path|
+          app.config.paths["db/migrate"] << path
+        end
+      end
+    end
+  end
+end

data/lib/rails_webhook_outbox/sender.rb

@@ -0,0 +1,58 @@
+require "net/http"
+require "uri"
+require "json"
+require "securerandom"
+
+module RailsWebhookOutbox
+  class Sender
+    def self.call(delivery)
+      new(delivery).call
+    end
+
+    def initialize(delivery)
+      @delivery = delivery
+    end
+
+    def call
+      uri = URI.parse(@delivery.subscription.url)
+      body = build_body
+      request = build_request(uri, body)
+      response = execute(uri, request)
+      raise DeliveryError.new(response) unless response.is_a?(Net::HTTPSuccess)
+      response
+    end
+
+    private
+
+    def build_body
+      JSON.generate(
+        event: @delivery.event,
+        delivered_at: Time.now.utc.iso8601,
+        data: @delivery.payload
+      )
+    end
+
+    def build_request(uri, body)
+      req = Net::HTTP::Post.new(uri)
+      req["Content-Type"] = "application/json"
+      req["X-Webhook-Signature"] = Signature.header_value(body, @delivery.subscription.secret)
+      req["X-Webhook-Event"] = @delivery.event
+      req["X-Webhook-Delivery"] = SecureRandom.uuid
+      req["X-Webhook-Timestamp"] = Time.now.utc.to_i.to_s
+      req.body = body
+      req
+    end
+
+    def execute(uri, request)
+      timeout = RailsWebhookOutbox.config.request_timeout
+      Net::HTTP.start(
+        uri.host, uri.port,
+        use_ssl: uri.scheme == "https",
+        open_timeout: timeout,
+        read_timeout: timeout
+      ) do |http|
+        http.request(request)
+      end
+    end
+  end
+end

data/lib/rails_webhook_outbox/signature.rb

@@ -0,0 +1,14 @@
+require "openssl"
+
+module RailsWebhookOutbox
+  module Signature
+    def self.sign(payload, secret, algorithm)
+      OpenSSL::HMAC.hexdigest(algorithm.to_s.upcase, secret, payload)
+    end
+
+    def self.header_value(payload, secret)
+      algorithm = RailsWebhookOutbox.config.signing_algorithm
+      "#{algorithm}=#{sign(payload, secret, algorithm)}"
+    end
+  end
+end

data/lib/rails_webhook_outbox/version.rb

@@ -0,0 +1,3 @@
+module RailsWebhookOutbox
+  VERSION = "0.1.0"
+end

data/lib/rails_webhook_outbox.rb

@@ -0,0 +1,39 @@
+require "rails_webhook_outbox/version"
+require "rails_webhook_outbox/configuration"
+require "rails_webhook_outbox/signature"
+require "rails_webhook_outbox/delivery_error"
+require "rails_webhook_outbox/sender"
+require "rails_webhook_outbox/dispatchable"
+require "rails_webhook_outbox/engine"
+
+module RailsWebhookOutbox
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    alias_method :config, :configuration
+
+    def configure
+      yield(configuration)
+    end
+
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+
+    def dispatch(event, payload)
+      Subscription.active.each do |subscription|
+        next unless subscription.subscribes_to?(event)
+
+        delivery = Delivery.create!(
+          subscription: subscription,
+          event: event,
+          payload: payload
+        )
+
+        DeliveryJob.perform_later(delivery)
+      end
+    end
+  end
+end

data/lib/tasks/rails_webhook_outbox_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :rails_webhook_outbox do
+#   # Task goes here
+# end

metadata

@@ -0,0 +1,85 @@
+--- !ruby/object:Gem::Specification
+name: rails_webhook_outbox
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Chuck Smith
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.2'
+description: A Rails engine for sending outgoing webhooks with HMAC signing, ActiveJob-based
+  retry, and delivery logging.
+email:
+- eclectic-coding@users.noreply.github.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- Rakefile
+- app/controllers/rails_webhook_outbox/application_controller.rb
+- app/jobs/rails_webhook_outbox/application_job.rb
+- app/jobs/rails_webhook_outbox/delivery_job.rb
+- app/mailers/rails_webhook_outbox/application_mailer.rb
+- app/models/rails_webhook_outbox/application_record.rb
+- app/models/rails_webhook_outbox/delivery.rb
+- app/models/rails_webhook_outbox/subscription.rb
+- config/routes.rb
+- db/migrate/20260624000001_create_webhook_outbox_subscriptions.rb
+- db/migrate/20260624000002_create_webhook_outbox_deliveries.rb
+- lib/generators/rails_webhook_outbox/install/install_generator.rb
+- lib/generators/rails_webhook_outbox/install/templates/create_webhook_outbox_deliveries.rb
+- lib/generators/rails_webhook_outbox/install/templates/create_webhook_outbox_subscriptions.rb
+- lib/generators/rails_webhook_outbox/install/templates/initializer.rb
+- lib/rails_webhook_outbox.rb
+- lib/rails_webhook_outbox/configuration.rb
+- lib/rails_webhook_outbox/delivery_error.rb
+- lib/rails_webhook_outbox/dispatchable.rb
+- lib/rails_webhook_outbox/engine.rb
+- lib/rails_webhook_outbox/sender.rb
+- lib/rails_webhook_outbox/signature.rb
+- lib/rails_webhook_outbox/version.rb
+- lib/tasks/rails_webhook_outbox_tasks.rake
+homepage: https://github.com/eclectic-coding/rails_webhook_outbox
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/eclectic-coding/rails_webhook_outbox
+  source_code_uri: https://github.com/eclectic-coding/rails_webhook_outbox
+  changelog_uri: https://github.com/eclectic-coding/rails_webhook_outbox/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Outgoing webhooks for Rails with HMAC signing and ActiveJob retry
+test_files: []