rails_webhook_outbox 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 743d24ea18d5fad259efd9369fc228866eeb883e6f5911d96d081e304a62aca4
-  data.tar.gz: 9bd087f6a44e6eedb95b1ccd97fd9e52423c547f67f3d4d384eb5b407fdfee1e
+  metadata.gz: 72234fe9faabd82b982170783792dd9d50188b8a727b72f46ab30e5f8d36929a
+  data.tar.gz: bf7c3b453aaf3c66d1ce4a06fb2a72d169dfcae330cc3ba8819dbe75de020e67
 SHA512:
-  metadata.gz: 02b57c5bfb462a475dde3036a6ee5f18fe033faaaa808d03d1bd45417f687162210ad6987aee0135775a5d2298fa989d65ac24c06762201cffcad05bb66938f8
-  data.tar.gz: 5fdaac46aa8ad0591e5c0837df73d9d6bd10a9af15f02f96415ac45ced02e85608198bc8beed2baaa42449e93986ac3a816b9da0e66ae8ff5ff636c2c6807a1a
+  metadata.gz: 6363ae17aa5037b3c58e8169d97c7bb6c997f5e8e515a963aa5964f9aba9ffe29c4e09805f1bcd69e69f569e7887b2e1f7c69119c93c25f8004258809ab6581e
+  data.tar.gz: 7009433848a306ff1465d73d526a9378230ca7730fa7a9bcc4aa3159091bdaab663f442e2124ff3b6507a9fb63adb65bda814607a3d56fb297ffc04b5018cc25

data/README.md

@@ -17,10 +17,16 @@ A Rails engine for sending outgoing webhooks with HMAC signing, ActiveJob-based
 - [Subscriptions](#subscriptions)
 - [Deliveries](#deliveries)
 - [Async Delivery](#async-delivery)
+- [Instrumentation](#instrumentation)
+- [Logging](#logging)
 - [HTTP Request Format](#http-request-format)
 - [HMAC Signing](#hmac-signing)
+- [Secret Rotation](#secret-rotation)
+- [Circuit Breaker](#circuit-breaker)
+- [Rake Tasks](#rake-tasks)
 - [Usage](#usage)
 - [Manual Dispatch](#manual-dispatch)
+- [Testing](#testing)
 - [Development](#development)
   - [Dummy App](#dummy-app)
 - [Contributing](#contributing)
@@ -64,9 +70,16 @@ RailsWebhookOutbox.configure do |config|
   config.retry_backoff      = :exponential
   config.request_timeout    = 5
   config.delivery_job_queue = :webhooks
+  config.max_payload_size   = 65_536  # bytes; set to nil or 0 to disable
+  config.secret_rotation_grace_period = 24.hours
+  config.circuit_breaker_threshold = 10  # consecutive permanent failures before auto-disabling; nil or 0 disables
 end
 ```
 
+When `config.events` is set, both `dispatch` and `Dispatchable` callbacks will raise `ArgumentError` if the event name is not in the list. Leave `config.events` empty to skip validation entirely.
+
+If the JSON-serialised payload exceeds `config.max_payload_size` bytes, `RailsWebhookOutbox::PayloadSizeError` is raised before any `Delivery` record is created or job enqueued. The default limit is 64 KB (`65_536` bytes).
+
 [Back to top](#table-of-contents)
 
 ## Subscriptions
@@ -146,7 +159,7 @@ The job uses polynomial backoff (`:polynomially_longer`) between retries — wai
 | 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`.
+Every attempt (success or failure) increments `delivery.attempts` and stores the `response_code` and `response_body`. Successful deliveries also set `delivered_at`. Retryable failures set `next_retry_at` to the estimated time of the next attempt (based on the polynomial formula `executions⁴ + 2` seconds); it is cleared to `nil` once all retries are exhausted.
 
 Enqueue a delivery manually:
 
@@ -156,6 +169,69 @@ RailsWebhookOutbox::DeliveryJob.perform_later(delivery)
 
 [Back to top](#table-of-contents)
 
+## Instrumentation
+
+`DeliveryJob` publishes `ActiveSupport::Notifications` events you can subscribe to for logging, metrics, or alerting:
+
+| Event | When |
+|-------|------|
+| `webhook.delivered.rails_webhook_outbox` | Delivery succeeded (2xx response) |
+| `webhook.failed.rails_webhook_outbox` | All retries exhausted — permanent failure |
+| `webhook.circuit_breaker_tripped.rails_webhook_outbox` | A permanent failure auto-disabled the subscription — see [Circuit Breaker](#circuit-breaker) |
+
+`webhook.delivered` / `webhook.failed` payloads include:
+
+| Key | Type | Description |
+|-----|------|-------------|
+| `event` | String | Webhook event name, e.g. `"order.created"` |
+| `subscription_id` | Integer | ID of the `Subscription` record |
+| `delivery_id` | Integer | ID of the `Delivery` record |
+| `duration` | Integer | HTTP round-trip time in milliseconds |
+
+`webhook.circuit_breaker_tripped` payloads include `subscription_id` and `consecutive_failures`.
+
+Subscribe in an initializer:
+
+```ruby
+ActiveSupport::Notifications.subscribe("webhook.delivered.rails_webhook_outbox") do |*args|
+  event = ActiveSupport::Notifications::Event.new(*args)
+  Rails.logger.info "[webhook] delivered #{event.payload[:event]} in #{event.payload[:duration]}ms"
+end
+
+ActiveSupport::Notifications.subscribe("webhook.failed.rails_webhook_outbox") do |*args|
+  event = ActiveSupport::Notifications::Event.new(*args)
+  Sentry.capture_message("Webhook permanently failed", extra: event.payload)
+end
+```
+
+[Back to top](#table-of-contents)
+
+## Logging
+
+`Sender` and `DeliveryJob` emit structured `Rails.logger` output for every delivery lifecycle event. All lines are prefixed `[RailsWebhookOutbox]` in key=value format, making them easy to grep and compatible with Logfmt-aware log aggregators (Datadog, Papertrail, etc.).
+
+| Source | Level | When | Keys logged |
+|--------|-------|------|-------------|
+| `Sender` | `info` | Before each HTTP call | `event`, `key` (idempotency key), `url` |
+| `DeliveryJob` | `info` | Successful delivery | `event`, `delivery_id`, `subscription_id`, `status`, `duration` |
+| `DeliveryJob` | `warn` | Retryable failure | `event`, `delivery_id`, `subscription_id`, `status`, `attempt`, `next_retry_at` |
+| `DeliveryJob` | `error` | Permanent failure (all retries exhausted) | `event`, `delivery_id`, `subscription_id`, `status`, `attempts` |
+| `DeliveryJob` | `warn` | Circuit breaker tripped | `subscription_id`, `consecutive_failures` |
+
+Example lines:
+
+```
+[RailsWebhookOutbox] attempt event=order.created key=550e8400-e29b-41d4-a716-446655440000 url=https://example.com/webhooks
+[RailsWebhookOutbox] delivered event=order.created delivery_id=1 subscription_id=1 status=200 duration=45ms
+[RailsWebhookOutbox] retry event=order.created delivery_id=1 subscription_id=1 status=503 attempt=1 next_retry_at=2026-07-01T00:00:13Z
+[RailsWebhookOutbox] failed event=order.created delivery_id=1 subscription_id=1 status=503 attempts=3
+[RailsWebhookOutbox] circuit_breaker_tripped subscription_id=1 consecutive_failures=10
+```
+
+No configuration is required — logging is always on and respects your application's log level.
+
+[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:
@@ -175,6 +251,8 @@ X-Webhook-Timestamp: 1719100800
 }
 ```
 
+`X-Webhook-Delivery` is the delivery's `idempotency_key` — a UUID generated once when the `Delivery` record is created and reused on every retry attempt. Subscribers can use this value to deduplicate incoming webhooks.
+
 Non-2xx responses raise `RailsWebhookOutbox::DeliveryError`, which carries `response_code` and `response_body` for logging and retry decisions.
 
 [Back to top](#table-of-contents)
@@ -187,11 +265,14 @@ Every outgoing request includes an `X-Webhook-Signature` header (configurable) c
 X-Webhook-Signature: sha256=a1b2c3d4...
 ```
 
-Subscribers can verify the signature:
+Subscribers can verify the signature. The header may contain more than one comma-separated
+`algorithm=digest` pair while a subscription's secret is [rotating](#secret-rotation), so check
+each one and accept the request if any match:
 
 ```ruby
-expected = RailsWebhookOutbox::Signature.header_value(raw_body, subscription.secret)
-Rack::Utils.secure_compare(expected, request.headers["X-Webhook-Signature"])
+expected = RailsWebhookOutbox::Signature.sign(raw_body, subscription.secret, :sha256)
+signatures = request.headers["X-Webhook-Signature"].to_s.split(",")
+valid = signatures.any? { |sig| Rack::Utils.secure_compare(sig, "sha256=#{expected}") }
 ```
 
 You can also call the primitives directly:
@@ -206,6 +287,83 @@ RailsWebhookOutbox::Signature.header_value(payload, secret)
 # => "sha256=a1b2c3d4..."
 ```
 
+`header_value` also accepts an array of secrets, signing the payload with each one and joining the
+results with a comma — this is how dual-secret signing works during [secret rotation](#secret-rotation).
+
+[Back to top](#table-of-contents)
+
+## Secret Rotation
+
+Rotate a subscription's HMAC secret without dropping any webhook deliveries:
+
+```ruby
+sub.rotate_secret!
+```
+
+This generates a new secret and moves the old one to `previous_secret`, valid until
+`previous_secret_expires_at` (set from `config.secret_rotation_grace_period`, default 24 hours).
+Pass `grace_period:` to override it for a single rotation:
+
+```ruby
+sub.rotate_secret!(grace_period: 3.days)
+```
+
+Calling `rotate_secret!` again while a previous secret is still within its grace period raises
+`RailsWebhookOutbox::SecretRotationError`, since the schema only holds one previous secret — doing
+so would silently invalidate a secret subscribers may not have finished transitioning to yet. Pass
+`force: true` to rotate anyway and discard it immediately.
+
+While `previous_secret` is still active, every outgoing request is signed with **both** secrets —
+`X-Webhook-Signature` carries a comma-separated list of `algorithm=digest` pairs:
+
+```
+X-Webhook-Signature: sha256=<new-secret-digest>,sha256=<previous-secret-digest>
+```
+
+See [HMAC Signing](#hmac-signing) for how subscribers should verify a header that may contain more
+than one signature.
+
+[Back to top](#table-of-contents)
+
+## Circuit Breaker
+
+Each `Subscription` tracks `consecutive_failures` — how many deliveries in a row have permanently
+failed (all retries exhausted). A successful delivery resets it to zero.
+
+Once `consecutive_failures` reaches `config.circuit_breaker_threshold` (default 10), the
+subscription is automatically disabled (`active: false`) so a persistently failing endpoint stops
+being hammered — deliveries already in flight are skipped rather than retried further once their
+subscription is disabled — and `webhook.circuit_breaker_tripped.rails_webhook_outbox` is published:
+
+```ruby
+ActiveSupport::Notifications.subscribe("webhook.circuit_breaker_tripped.rails_webhook_outbox") do |*args|
+  event = ActiveSupport::Notifications::Event.new(*args)
+  Sentry.capture_message("Webhook subscription auto-disabled",
+    extra: event.payload.slice(:subscription_id, :consecutive_failures))
+end
+```
+
+Set `config.circuit_breaker_threshold` to `nil` or `0` to disable auto-disabling entirely. Retryable
+(non-final) failures don't count towards the threshold — only a delivery that has exhausted all
+retries counts as one consecutive failure. Re-enable a tripped subscription with
+`sub.update!(active: true)`; `consecutive_failures` resets to zero immediately on reactivation, so a
+single subsequent failure won't instantly re-trip the breaker.
+
+[Back to top](#table-of-contents)
+
+## Rake Tasks
+
+```bash
+bin/rails webhook_outbox:retry_failed         # re-enqueue all failed deliveries for retry
+bin/rails webhook_outbox:list_subscriptions   # list subscriptions with status, events, and failure count
+bin/rails webhook_outbox:cleanup[7]           # delete delivered/failed deliveries older than N days
+```
+
+`retry_failed` resets each failed delivery to `pending` and enqueues a `DeliveryJob`; deliveries
+whose subscription has since been disabled are skipped by the job itself, not by the task.
+`cleanup[days]` requires a positive integer argument and only removes deliveries in a terminal
+state (`delivered` or `failed`) — `pending` deliveries are never deleted.
+
 [Back to top](#table-of-contents)
 
 ## Usage
@@ -257,12 +415,52 @@ RailsWebhookOutbox.dispatch("payment.completed", {
 })
 ```
 
-`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.
+`dispatch` validates the event name against `config.events` (if configured), then 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.
+
+You can also validate an event name directly without dispatching:
+
+```ruby
+RailsWebhookOutbox.validate_event!("payment.completed")
+# raises ArgumentError if the event is not in config.events
+```
 
 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)
 
+## Testing
+
+Enable test mode in your `rails_helper.rb` to suppress HTTP calls and DB writes during specs:
+
+```ruby
+require "rails_webhook_outbox/rspec_matchers"
+
+RailsWebhookOutbox.configure { |c| c.test_mode = true }
+
+RSpec.configure do |config|
+  config.before { RailsWebhookOutbox::Testing.clear_deliveries! }
+end
+```
+
+When `test_mode` is `true`, dispatched events are captured in memory instead of creating `Delivery` records or enqueuing jobs. Use the `dispatch_webhook` matcher to assert on them:
+
+```ruby
+expect { order.save! }.to dispatch_webhook("order.created")
+expect { order.save! }.to dispatch_webhook("order.created").with_payload({ id: order.id })
+expect { order.save! }.not_to dispatch_webhook("order.updated")
+```
+
+Inspect captured events directly if needed:
+
+```ruby
+RailsWebhookOutbox::Testing.deliveries
+# => [{ event: "order.created", payload: { "id" => 1, ... } }]
+```
+
+`DeliveryJob` also respects `test_mode` — if a job is enqueued and performed directly in a test, it marks the delivery as `delivered` without making an HTTP call.
+
+[Back to top](#table-of-contents)
+
 ## Development
 
 ```bash

data/app/jobs/rails_webhook_outbox/delivery_job.rb

@@ -4,7 +4,18 @@ module RailsWebhookOutbox
     retry_on RailsWebhookOutbox::DeliveryError, wait: :polynomially_longer, attempts: :unlimited
 
     def perform(delivery)
+      return skip_disabled_subscription(delivery) unless delivery.subscription.active?
+
+      if RailsWebhookOutbox.config.test_mode
+        delivery.update!(status: :delivered, attempts: delivery.attempts + 1, delivered_at: Time.current)
+        delivery.subscription.record_delivery_success!
+        notify("webhook.delivered.rails_webhook_outbox", delivery, 0)
+        return
+      end
+
+      start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
       response = Sender.call(delivery)
+      duration_ms = elapsed_ms(start)
       delivery.update!(
         status: :delivered,
         response_code: response.code.to_i,
@@ -12,15 +23,57 @@ module RailsWebhookOutbox
         delivered_at: Time.current,
         attempts: delivery.attempts + 1
       )
+      delivery.subscription.record_delivery_success!
+      Rails.logger.info { "[RailsWebhookOutbox] delivered event=#{delivery.event} delivery_id=#{delivery.id} subscription_id=#{delivery.subscription_id} status=#{response.code} duration=#{duration_ms}ms" }
+      notify("webhook.delivered.rails_webhook_outbox", delivery, duration_ms)
     rescue DeliveryError => e
+      duration_ms = elapsed_ms(start)
       max_retries = RailsWebhookOutbox.config.max_retries
+      final = executions >= 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
+        status: final ? :failed : :pending,
+        next_retry_at: final ? nil : Time.current + ((executions**4) + 2).seconds
       )
-      raise if executions < max_retries
+      if final
+        Rails.logger.error { "[RailsWebhookOutbox] failed event=#{delivery.event} delivery_id=#{delivery.id} subscription_id=#{delivery.subscription_id} status=#{e.response_code} attempts=#{delivery.attempts}" }
+        notify("webhook.failed.rails_webhook_outbox", delivery, duration_ms)
+        record_failure_and_notify_if_tripped(delivery)
+      else
+        Rails.logger.warn { "[RailsWebhookOutbox] retry event=#{delivery.event} delivery_id=#{delivery.id} subscription_id=#{delivery.subscription_id} status=#{e.response_code} attempt=#{delivery.attempts} next_retry_at=#{delivery.next_retry_at.utc.iso8601}" }
+        raise
+      end
+    end
+
+    private
+
+    def skip_disabled_subscription(delivery)
+      delivery.update!(status: :failed, next_retry_at: nil)
+      Rails.logger.warn { "[RailsWebhookOutbox] skipped event=#{delivery.event} delivery_id=#{delivery.id} subscription_id=#{delivery.subscription_id} reason=subscription_inactive" }
+    end
+
+    def elapsed_ms(start)
+      ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start) * 1000).round
+    end
+
+    def notify(event_name, delivery, duration_ms)
+      ActiveSupport::Notifications.instrument(event_name,
+        event: delivery.event,
+        subscription_id: delivery.subscription_id,
+        delivery_id: delivery.id,
+        duration: duration_ms)
+    end
+
+    def record_failure_and_notify_if_tripped(delivery)
+      return unless delivery.subscription.record_delivery_failure!
+
+      subscription = delivery.subscription
+      Rails.logger.warn { "[RailsWebhookOutbox] circuit_breaker_tripped subscription_id=#{subscription.id} consecutive_failures=#{subscription.consecutive_failures}" }
+      ActiveSupport::Notifications.instrument("webhook.circuit_breaker_tripped.rails_webhook_outbox",
+        subscription_id: subscription.id,
+        consecutive_failures: subscription.consecutive_failures)
     end
   end
 end

data/app/models/rails_webhook_outbox/delivery.rb

@@ -6,9 +6,18 @@ module RailsWebhookOutbox
 
     enum :status, { pending: 0, delivered: 1, failed: 2 }
 
+    before_validation :generate_idempotency_key, on: :create
+
     validates :event, presence: true
     validates :payload, presence: true
+    validates :idempotency_key, presence: true
 
     scope :retryable, -> { pending }
+
+    private
+
+    def generate_idempotency_key
+      self.idempotency_key ||= SecureRandom.uuid
+    end
   end
 end

data/app/models/rails_webhook_outbox/subscription.rb

@@ -7,6 +7,7 @@ module RailsWebhookOutbox
     attribute :active, :boolean, default: true
 
     before_validation :generate_secret, on: :create
+    before_save :reset_consecutive_failures_on_reactivation
 
     validates :url, presence: true, format: { with: URL_FORMAT, message: "must be a valid HTTP or HTTPS URL" }
     validates :secret, presence: true
@@ -18,10 +19,52 @@ module RailsWebhookOutbox
       events.include?(event.to_s)
     end
 
+    def rotate_secret!(grace_period: RailsWebhookOutbox.config.secret_rotation_grace_period, force: false)
+      raise SecretRotationError if previous_secret_active? && !force
+
+      update!(
+        previous_secret: secret,
+        previous_secret_expires_at: Time.current + grace_period,
+        secret: generate_secret_value
+      )
+    end
+
+    def previous_secret_active?
+      previous_secret.present? && previous_secret_expires_at.present? && previous_secret_expires_at.future?
+    end
+
+    def signing_secrets
+      previous_secret_active? ? [secret, previous_secret] : [secret]
+    end
+
+    def record_delivery_success!
+      update!(consecutive_failures: 0) if consecutive_failures != 0
+    end
+
+    def record_delivery_failure!(threshold: RailsWebhookOutbox.config.circuit_breaker_threshold)
+      with_lock do
+        next false unless active?
+
+        increment!(:consecutive_failures)
+        next false unless threshold&.positive? && consecutive_failures >= threshold
+
+        update!(active: false)
+        true
+      end
+    end
+
     private
 
     def generate_secret
-      self.secret ||= SecureRandom.hex(32)
+      self.secret ||= generate_secret_value
+    end
+
+    def generate_secret_value
+      SecureRandom.hex(32)
+    end
+
+    def reset_consecutive_failures_on_reactivation
+      self.consecutive_failures = 0 if active_changed?(from: false, to: true)
     end
   end
 end

data/db/migrate/20260629000002_add_idempotency_key_to_webhook_outbox_deliveries.rb

@@ -0,0 +1,6 @@
+class AddIdempotencyKeyToWebhookOutboxDeliveries < ActiveRecord::Migration[7.2]
+  def change
+    add_column :webhook_outbox_deliveries, :idempotency_key, :string
+    add_index :webhook_outbox_deliveries, :idempotency_key, unique: true
+  end
+end

data/db/migrate/20260701000001_add_secret_rotation_to_webhook_outbox_subscriptions.rb

@@ -0,0 +1,6 @@
+class AddSecretRotationToWebhookOutboxSubscriptions < ActiveRecord::Migration[7.2]
+  def change
+    add_column :webhook_outbox_subscriptions, :previous_secret, :string
+    add_column :webhook_outbox_subscriptions, :previous_secret_expires_at, :datetime
+  end
+end

data/db/migrate/20260701000002_add_consecutive_failures_to_webhook_outbox_subscriptions.rb

@@ -0,0 +1,5 @@
+class AddConsecutiveFailuresToWebhookOutboxSubscriptions < ActiveRecord::Migration[7.2]
+  def change
+    add_column :webhook_outbox_subscriptions, :consecutive_failures, :integer, null: false, default: 0
+  end
+end

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

@@ -16,11 +16,11 @@ module RailsWebhookOutbox
 
       def copy_migrations
         migration_template(
-          "create_webhook_outbox_subscriptions.rb",
+          "create_webhook_outbox_subscriptions.rb.tt",
           "db/migrate/create_webhook_outbox_subscriptions.rb"
         )
         migration_template(
-          "create_webhook_outbox_deliveries.rb",
+          "create_webhook_outbox_deliveries.rb.tt",
           "db/migrate/create_webhook_outbox_deliveries.rb"
         )
       end

data/lib/generators/rails_webhook_outbox/install/templates/{create_webhook_outbox_deliveries.rb → create_webhook_outbox_deliveries.rb.tt}

@@ -8,6 +8,7 @@ class CreateWebhookOutboxDeliveries < ActiveRecord::Migration[<%= ActiveRecord::
       t.integer :response_code
       t.text :response_body
       t.integer :attempts, null: false, default: 0
+      t.string :idempotency_key
       t.datetime :delivered_at
       t.datetime :next_retry_at
       t.timestamps
@@ -17,4 +18,4 @@ class CreateWebhookOutboxDeliveries < ActiveRecord::Migration[<%= ActiveRecord::
     add_index :webhook_outbox_deliveries, :event
     add_index :webhook_outbox_deliveries, [:subscription_id, :created_at]
   end
-end
+end

data/lib/generators/rails_webhook_outbox/install/templates/{create_webhook_outbox_subscriptions.rb → create_webhook_outbox_subscriptions.rb.tt}

@@ -3,8 +3,11 @@ class CreateWebhookOutboxSubscriptions < ActiveRecord::Migration[<%= ActiveRecor
     create_table :webhook_outbox_subscriptions do |t|
       t.string :url, null: false
       t.string :secret, null: false
+      t.string :previous_secret
+      t.datetime :previous_secret_expires_at
       t.json :events, null: false, default: []
       t.boolean :active, null: false, default: true
+      t.integer :consecutive_failures, null: false, default: 0
       t.string :description
       t.json :metadata, default: {}
       t.timestamps

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

@@ -19,4 +19,12 @@ RailsWebhookOutbox.configure do |config|
 
   # ActiveJob queue for delivery jobs.
   config.delivery_job_queue = :webhooks
+
+  # Maximum payload size in bytes. Raises PayloadSizeError before enqueuing if exceeded.
+  # Set to nil or 0 to disable.
+  config.max_payload_size = 65_536
+
+  # Set to true in test environments to suppress HTTP calls and capture dispatched events
+  # in RailsWebhookOutbox::Testing.deliveries instead of creating DB records or jobs.
+  # config.test_mode = false
 end

data/lib/rails_webhook_outbox/configuration.rb

@@ -5,7 +5,8 @@ module RailsWebhookOutbox
 
     attr_accessor :events, :signing_algorithm, :signing_header,
                   :max_retries, :retry_backoff, :request_timeout,
-                  :delivery_job_queue
+                  :delivery_job_queue, :max_payload_size, :test_mode,
+                  :secret_rotation_grace_period, :circuit_breaker_threshold
 
     def initialize
       @events = []
@@ -15,6 +16,10 @@ module RailsWebhookOutbox
       @retry_backoff = :exponential
       @request_timeout = 5
       @delivery_job_queue = :webhooks
+      @max_payload_size = 65_536
+      @test_mode = false
+      @secret_rotation_grace_period = 24.hours
+      @circuit_breaker_threshold = 10
     end
 
     def signing_algorithm=(value)
@@ -34,5 +39,13 @@ module RailsWebhookOutbox
 
       @retry_backoff = value
     end
+
+    def secret_rotation_grace_period=(value)
+      unless value.is_a?(Numeric) && value.positive?
+        raise ArgumentError, "secret_rotation_grace_period must be a positive duration"
+      end
+
+      @secret_rotation_grace_period = value
+    end
   end
 end

data/lib/rails_webhook_outbox/dispatchable.rb

@@ -24,7 +24,15 @@ module RailsWebhookOutbox
     def _dispatch_webhook(event, condition)
       return if condition && !instance_exec(&condition)
 
+      RailsWebhookOutbox.validate_event!(event)
+
       payload = webhook_payload
+      RailsWebhookOutbox.validate_payload_size!(payload)
+
+      if RailsWebhookOutbox.config.test_mode
+        RailsWebhookOutbox::Testing.deliveries << { event: event.to_s, payload: payload }
+        return
+      end
 
       Subscription.active.each do |subscription|
         next unless subscription.subscribes_to?(event)

data/lib/rails_webhook_outbox/payload_size_error.rb

@@ -0,0 +1,7 @@
+module RailsWebhookOutbox
+  class PayloadSizeError < StandardError
+    def initialize(size, max)
+      super("Payload too large: #{size} bytes exceeds the #{max}-byte limit")
+    end
+  end
+end

data/lib/rails_webhook_outbox/rspec_matchers.rb

@@ -0,0 +1,32 @@
+require "rails_webhook_outbox/testing"
+
+RSpec::Matchers.define :dispatch_webhook do |expected_event|
+  chain :with_payload do |payload|
+    @expected_payload = payload
+  end
+
+  match do |block|
+    before = RailsWebhookOutbox::Testing.deliveries.dup
+    block.call
+    @dispatched = RailsWebhookOutbox::Testing.deliveries.drop(before.size)
+    @dispatched.any? do |d|
+      d[:event] == expected_event.to_s &&
+        (@expected_payload.nil? || d[:payload] == @expected_payload)
+    end
+  end
+
+  supports_block_expectations
+
+  failure_message do
+    if @dispatched.empty?
+      "expected #{expected_event.inspect} webhook to be dispatched, but no webhooks were dispatched"
+    else
+      events = @dispatched.map { |d| d[:event].inspect }.join(", ")
+      "expected #{expected_event.inspect} webhook to be dispatched, but dispatched: #{events}"
+    end
+  end
+
+  failure_message_when_negated do
+    "expected #{expected_event.inspect} webhook not to be dispatched, but it was"
+  end
+end

data/lib/rails_webhook_outbox/secret_rotation_error.rb

@@ -0,0 +1,8 @@
+module RailsWebhookOutbox
+  class SecretRotationError < StandardError
+    def initialize
+      super("Cannot rotate secret: the previous secret is still within its grace period. " \
+            "Pass force: true to rotate anyway and immediately invalidate it.")
+    end
+  end
+end

data/lib/rails_webhook_outbox/sender.rb

@@ -17,6 +17,7 @@ module RailsWebhookOutbox
       uri = URI.parse(@delivery.subscription.url)
       body = build_body
       request = build_request(uri, body)
+      Rails.logger.info { "[RailsWebhookOutbox] attempt event=#{@delivery.event} key=#{@delivery.idempotency_key} url=#{uri}" }
       response = execute(uri, request)
       raise DeliveryError.new(response) unless response.is_a?(Net::HTTPSuccess)
       response
@@ -35,9 +36,9 @@ module RailsWebhookOutbox
     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-Signature"] = Signature.header_value(body, @delivery.subscription.signing_secrets)
       req["X-Webhook-Event"] = @delivery.event
-      req["X-Webhook-Delivery"] = SecureRandom.uuid
+      req["X-Webhook-Delivery"] = @delivery.idempotency_key
       req["X-Webhook-Timestamp"] = Time.now.utc.to_i.to_s
       req.body = body
       req

data/lib/rails_webhook_outbox/signature.rb

@@ -6,9 +6,9 @@ module RailsWebhookOutbox
       OpenSSL::HMAC.hexdigest(algorithm.to_s.upcase, secret, payload)
     end
 
-    def self.header_value(payload, secret)
+    def self.header_value(payload, secrets)
       algorithm = RailsWebhookOutbox.config.signing_algorithm
-      "#{algorithm}=#{sign(payload, secret, algorithm)}"
+      Array(secrets).map { |secret| "#{algorithm}=#{sign(payload, secret, algorithm)}" }.join(",")
     end
   end
 end

data/lib/rails_webhook_outbox/testing.rb

@@ -0,0 +1,13 @@
+module RailsWebhookOutbox
+  module Testing
+    class << self
+      def deliveries
+        @deliveries ||= []
+      end
+
+      def clear_deliveries!
+        @deliveries = []
+      end
+    end
+  end
+end

data/lib/rails_webhook_outbox/version.rb

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

data/lib/rails_webhook_outbox.rb

@@ -2,6 +2,9 @@ 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/payload_size_error"
+require "rails_webhook_outbox/secret_rotation_error"
+require "rails_webhook_outbox/testing"
 require "rails_webhook_outbox/sender"
 require "rails_webhook_outbox/dispatchable"
 require "rails_webhook_outbox/engine"
@@ -22,7 +25,31 @@ module RailsWebhookOutbox
       @configuration = Configuration.new
     end
 
+    def validate_event!(event)
+      registered = config.events
+      return if registered.empty?
+      return if registered.include?(event.to_s)
+
+      raise ArgumentError, "Unknown event #{event.inspect}. Registered events: #{registered.join(", ")}"
+    end
+
+    def validate_payload_size!(payload)
+      max = config.max_payload_size
+      return unless max && max > 0
+
+      size = JSON.generate(payload).bytesize
+      raise PayloadSizeError.new(size, max) if size > max
+    end
+
     def dispatch(event, payload)
+      validate_event!(event)
+      validate_payload_size!(payload)
+
+      if config.test_mode
+        Testing.deliveries << { event: event.to_s, payload: payload }
+        return
+      end
+
       Subscription.active.each do |subscription|
         next unless subscription.subscribes_to?(event)
 

data/lib/tasks/rails_webhook_outbox_tasks.rake

@@ -1,4 +1,51 @@
-# desc "Explaining what the task does"
-# task :rails_webhook_outbox do
-#   # Task goes here
-# end
+namespace :webhook_outbox do
+  desc "Re-enqueue failed deliveries for retry"
+  task retry_failed: :environment do
+    deliveries = RailsWebhookOutbox::Delivery.failed
+    count = deliveries.count
+
+    if count.zero?
+      puts "No failed deliveries to retry"
+    else
+      deliveries.find_each do |delivery|
+        delivery.update!(status: :pending, next_retry_at: nil)
+        RailsWebhookOutbox::DeliveryJob.perform_later(delivery)
+      end
+      puts "Re-enqueued #{count} failed #{"delivery".pluralize(count)} for retry"
+    end
+  end
+
+  desc "List all webhook subscriptions"
+  task list_subscriptions: :environment do
+    subscriptions = RailsWebhookOutbox::Subscription.order(:id)
+
+    if subscriptions.none?
+      puts "No subscriptions found"
+    else
+      subscriptions.find_each do |subscription|
+        puts format(
+          "#%d [%s] %s events=%s failures=%d",
+          subscription.id,
+          subscription.active? ? "active" : "inactive",
+          subscription.url,
+          subscription.events.join(","),
+          subscription.consecutive_failures
+        )
+      end
+    end
+  end
+
+  desc "Delete delivered and failed deliveries older than the given number of days"
+  task :cleanup, [:days] => :environment do |_task, args|
+    days = args[:days].to_i
+
+    if days <= 0
+      puts "Usage: rake webhook_outbox:cleanup[days] (days must be a positive integer)"
+    else
+      scope = RailsWebhookOutbox::Delivery.where(status: [:delivered, :failed]).where(created_at: ...days.days.ago)
+      count = scope.count
+      scope.delete_all
+      puts "Deleted #{count} #{"delivery".pluralize(count)} older than #{days} #{"day".pluralize(days)}"
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails_webhook_outbox
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Chuck Smith
@@ -44,17 +44,24 @@ files:
 - config/routes.rb
 - db/migrate/20260624000001_create_webhook_outbox_subscriptions.rb
 - db/migrate/20260624000002_create_webhook_outbox_deliveries.rb
+- db/migrate/20260629000002_add_idempotency_key_to_webhook_outbox_deliveries.rb
+- db/migrate/20260701000001_add_secret_rotation_to_webhook_outbox_subscriptions.rb
+- db/migrate/20260701000002_add_consecutive_failures_to_webhook_outbox_subscriptions.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/create_webhook_outbox_deliveries.rb.tt
+- lib/generators/rails_webhook_outbox/install/templates/create_webhook_outbox_subscriptions.rb.tt
 - 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/payload_size_error.rb
+- lib/rails_webhook_outbox/rspec_matchers.rb
+- lib/rails_webhook_outbox/secret_rotation_error.rb
 - lib/rails_webhook_outbox/sender.rb
 - lib/rails_webhook_outbox/signature.rb
+- lib/rails_webhook_outbox/testing.rb
 - lib/rails_webhook_outbox/version.rb
 - lib/tasks/rails_webhook_outbox_tasks.rake
 homepage: https://github.com/eclectic-coding/rails_webhook_outbox