webhook_inbox 0.1.0

data/app/views/webhook_inbox/dashboard/index.html.erb

@@ -0,0 +1,61 @@
+<div class="wi-stats">
+  <% total = @status_counts.values.sum %>
+  <div class="wi-stat">
+    <div class="wi-stat-label">Total</div>
+    <div class="wi-stat-value"><%= total %></div>
+  </div>
+  <% %w[pending processing processed failed].each do |s| %>
+    <div class="wi-stat">
+      <div class="wi-stat-label"><%= s.capitalize %></div>
+      <div class="wi-stat-value"><%= @status_counts[s] || 0 %></div>
+    </div>
+  <% end %>
+</div>
+
+<%= form_with url: webhook_inbox.dashboard_path, method: :get, local: true, class: "wi-filters" do |f| %>
+  <label>Status</label>
+  <%= f.select :status,
+        [["All", ""], *%w[pending processing processed failed].map { |s| [s.capitalize, s] }],
+        { selected: params[:status] },
+        { onChange: "this.form.submit()" } %>
+  <label>Provider</label>
+  <%= f.select :provider,
+        [["All", ""], *@providers.map { |p| [p.capitalize, p] }],
+        { selected: params[:provider] },
+        { onChange: "this.form.submit()" } %>
+<% end %>
+
+<table>
+  <thead>
+    <tr>
+      <th>Status</th>
+      <th>Provider</th>
+      <th>Event Type</th>
+      <th>Event ID</th>
+      <th>Attempts</th>
+      <th>Received</th>
+      <th></th>
+    </tr>
+  </thead>
+  <tbody>
+    <% if @events.empty? %>
+      <tr>
+        <td colspan="7" style="text-align:center; color:#94a3b8; padding:32px;">No events yet.</td>
+      </tr>
+    <% else %>
+      <% @events.each do |event| %>
+        <tr>
+          <td><%= status_badge(event.status) %></td>
+          <td><span class="wi-mono"><%= event.provider %></span></td>
+          <td><span class="wi-mono"><%= event.event_type %></span></td>
+          <td><span class="wi-mono" title="<%= event.event_id %>"><%= event.event_id&.truncate(24) %></span></td>
+          <td><%= event.attempts %></td>
+          <td><span title="<%= event.created_at %>"><%= event.created_at.strftime("%b %d %H:%M:%S") %></span></td>
+          <td>
+            <%= link_to "View", webhook_inbox.event_path(event), class: "wi-btn wi-btn-back" %>
+          </td>
+        </tr>
+      <% end %>
+    <% end %>
+  </tbody>
+</table>

data/app/views/webhook_inbox/dashboard/show.html.erb

@@ -0,0 +1,54 @@
+<div style="display:flex; justify-content:space-between; align-items:center; margin-bottom:20px;">
+  <%= link_to "← All Events", webhook_inbox.dashboard_path, class: "wi-btn wi-btn-back" %>
+  <%= button_to "Replay", webhook_inbox.replay_event_path(@event), method: :post, class: "wi-btn wi-btn-replay" %>
+</div>
+
+<div class="wi-detail-card">
+  <div class="wi-detail-row">
+    <span class="wi-detail-label">Status</span>
+    <%= status_badge(@event.status) %>
+  </div>
+  <div class="wi-detail-row">
+    <span class="wi-detail-label">Provider</span>
+    <span class="wi-mono"><%= @event.provider %></span>
+  </div>
+  <div class="wi-detail-row">
+    <span class="wi-detail-label">Event Type</span>
+    <span class="wi-mono"><%= @event.event_type %></span>
+  </div>
+  <div class="wi-detail-row">
+    <span class="wi-detail-label">Event ID</span>
+    <span class="wi-mono"><%= @event.event_id %></span>
+  </div>
+  <div class="wi-detail-row">
+    <span class="wi-detail-label">Attempts</span>
+    <span><%= @event.attempts %></span>
+  </div>
+  <div class="wi-detail-row">
+    <span class="wi-detail-label">Received</span>
+    <span><%= @event.created_at.strftime("%Y-%m-%d %H:%M:%S UTC") %></span>
+  </div>
+  <% if @event.processed_at %>
+    <div class="wi-detail-row">
+      <span class="wi-detail-label">Processed At</span>
+      <span><%= @event.processed_at.strftime("%Y-%m-%d %H:%M:%S UTC") %></span>
+    </div>
+  <% end %>
+
+  <% if @event.error_message.present? %>
+    <div style="margin-top:16px;">
+      <span class="wi-detail-label">Error</span>
+      <div class="wi-error"><%= @event.error_message %></div>
+    </div>
+  <% end %>
+
+  <div style="margin-top:20px;">
+    <div class="wi-detail-label" style="margin-bottom:8px;">Payload</div>
+    <% begin %>
+      <% pretty = JSON.pretty_generate(@event.parsed_payload) %>
+    <% rescue %>
+      <% pretty = @event.payload.to_s %>
+    <% end %>
+    <pre><%= pretty %></pre>
+  </div>
+</div>

data/config/routes.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+WebhookInbox::Engine.routes.draw do
+  root to: "dashboard#index", as: :dashboard
+  resources :events, only: [:show], controller: "dashboard" do
+    member do
+      post :replay
+    end
+  end
+end

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

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+
+module WebhookInbox
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates a WebhookInbox migration and initializer in your application."
+
+      def create_migration
+        migration_template "create_webhook_inbox_events.rb.erb",
+                           "db/migrate/create_webhook_inbox_events.rb"
+      end
+
+      def create_initializer
+        template "initializer.rb", "config/initializers/webhook_inbox.rb"
+      end
+
+      def show_readme
+        readme "README" if behavior == :invoke
+      end
+
+      private
+
+      def migration_version
+        "[#{ActiveRecord::VERSION::MAJOR}.#{ActiveRecord::VERSION::MINOR}]"
+      end
+    end
+  end
+end

data/lib/generators/webhook_inbox/install/templates/README

@@ -0,0 +1,33 @@
+===============================================================================
+
+  WebhookInbox installed!
+
+  Next steps:
+
+  1. Run the migration:
+     rails db:migrate
+
+  2. Configure your handlers in config/initializers/webhook_inbox.rb
+
+  3. Add a controller for each provider:
+
+     class StripeWebhooksController < ApplicationController
+       include WebhookInbox::Receiver
+       receive_from :stripe, secret: -> { ENV["STRIPE_WEBHOOK_SECRET"] }
+
+       def create
+         receive_webhook!
+       end
+     end
+
+  4. Add the route:
+
+     # config/routes.rb
+     post "/webhooks/stripe", to: "stripe_webhooks#create"
+
+     # Optional dashboard:
+     mount WebhookInbox::Engine => "/webhook_inbox"
+
+  5. Set STRIPE_WEBHOOK_SECRET in your environment.
+
+===============================================================================

data/lib/generators/webhook_inbox/install/templates/create_webhook_inbox_events.rb.erb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+class CreateWebhookInboxEvents < ActiveRecord::Migration<%= migration_version %>
+  def change
+    create_table :webhook_inbox_events do |t|
+      t.string   :provider,      null: false
+      t.string   :event_id,      null: false
+      t.string   :event_type
+      t.text     :payload,       null: false, default: "{}"
+      t.string   :status,        null: false, default: "pending"
+      t.integer  :attempts,      null: false, default: 0
+      t.text     :error_message
+      t.datetime :processed_at
+      t.timestamps
+    end
+
+    add_index :webhook_inbox_events, [:provider, :event_id], unique: true
+    add_index :webhook_inbox_events, :status
+    add_index :webhook_inbox_events, :created_at
+  end
+end

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

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+WebhookInbox.configure do |config|
+  # Register handlers for each provider + event type you want to handle.
+  # The block receives a WebhookInbox::Event object.
+  #
+  # config.on(:stripe, "customer.subscription.created") do |event|
+  #   CreateSubscriptionJob.perform_later(event.parsed_payload)
+  # end
+  #
+  # config.on(:stripe, "invoice.payment_failed") do |event|
+  #   NotifyPaymentFailedJob.perform_later(event.parsed_payload)
+  # end
+  #
+  # Catch-all for all Stripe events:
+  # config.on(:stripe, "*") do |event|
+  #   Rails.logger.info "[WebhookInbox] Received #{event.event_type}"
+  # end
+
+  # Queue name for ProcessJob (default: "webhooks")
+  # config.queue_name = "webhooks"
+
+  # Dashboard auth lambda — return truthy to allow access.
+  # Required in production. Uncomment and customize:
+  # config.dashboard_auth = ->(controller) { controller.current_user&.admin? }
+end

data/lib/webhook_inbox/configuration.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module WebhookInbox
+  class Configuration
+    attr_accessor :queue_name, :dashboard_auth
+
+    def initialize
+      @queue_name = "webhooks"
+      @dashboard_auth = nil
+      @handlers = {}
+    end
+
+    # Register a handler block for a given provider + event type.
+    # Use "*" as event_type to match any event from that provider.
+    #
+    #   config.on(:stripe, "customer.subscription.created") { |event| ... }
+    #   config.on(:stripe, "*") { |event| ... }
+    def on(provider, event_type, &block)
+      raise ArgumentError, "Handler block required" unless block
+
+      key = handler_key(provider, event_type)
+      @handlers[key] ||= []
+      @handlers[key] << block
+    end
+
+    # Returns all matching handler blocks for [provider, event_type].
+    # Includes exact matches and wildcard "*" handlers for the provider.
+    def handlers_for(provider, event_type)
+      exact    = @handlers[handler_key(provider, event_type)] || []
+      wildcard = @handlers[handler_key(provider, "*")] || []
+      exact + wildcard
+    end
+
+    private
+
+    def handler_key(provider, event_type)
+      "#{provider}:#{event_type}"
+    end
+  end
+end

data/lib/webhook_inbox/engine.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "rails"
+
+module WebhookInbox
+  class Engine < Rails::Engine
+    isolate_namespace WebhookInbox
+
+    initializer "webhook_inbox.initialize" do
+      WebhookInbox.configuration ||= WebhookInbox::Configuration.new
+    end
+
+    initializer "webhook_inbox.autoload_receiver" do
+      ActiveSupport.on_load(:action_controller) do
+        require "webhook_inbox/receiver"
+      end
+    end
+  end
+end

data/lib/webhook_inbox/providers/base.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module WebhookInbox
+  module Providers
+    class Base
+      # Extract the unique event ID from the raw body and request.
+      # @param raw_body [String] the raw request body string
+      # @param request  [ActionDispatch::Request]
+      # @return [String]
+      def event_id(raw_body, request)
+        raise NotImplementedError, "#{self.class}#event_id not implemented"
+      end
+
+      # Extract the event type string (e.g. "customer.subscription.created").
+      # @param raw_body [String]
+      # @param request  [ActionDispatch::Request]
+      # @return [String]
+      def event_type(raw_body, request)
+        raise NotImplementedError, "#{self.class}#event_type not implemented"
+      end
+
+      # Verify the provider signature. Raise WebhookInbox::SignatureError on failure.
+      # @param raw_body [String]
+      # @param request  [ActionDispatch::Request]
+      # @param secret   [String]
+      def verify!(raw_body, request, secret:)
+        raise NotImplementedError, "#{self.class}#verify! not implemented"
+      end
+    end
+  end
+end

data/lib/webhook_inbox/providers/stripe.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "openssl"
+require "json"
+require "active_support/security_utils"
+
+module WebhookInbox
+  module Providers
+    class Stripe < Base
+      SIG_HEADER = "HTTP_STRIPE_SIGNATURE"
+
+      def event_id(raw_body, _request)
+        JSON.parse(raw_body)["id"]
+      rescue JSON::ParserError
+        nil
+      end
+
+      def event_type(raw_body, _request)
+        JSON.parse(raw_body)["type"] || "unknown"
+      rescue JSON::ParserError
+        "unknown"
+      end
+
+      # Stripe signature format: "t=<timestamp>,v1=<hmac>,v0=<hmac>"
+      # We verify v1 (HMAC-SHA256 of "timestamp.body" signed with the webhook secret).
+      # Raises WebhookInbox::SignatureError if invalid.
+      def verify!(raw_body, request, secret:)
+        sig_header = request.env[SIG_HEADER]
+        raise WebhookInbox::SignatureError, "Missing Stripe-Signature header" if sig_header.blank?
+
+        parts = sig_header.split(",").each_with_object({}) do |part, hash|
+          k, v = part.split("=", 2)
+          hash[k] = v if k && v
+        end
+        timestamp = parts["t"]
+        received  = parts["v1"]
+
+        raise WebhookInbox::SignatureError, "Malformed Stripe-Signature header" unless timestamp && received
+
+        signed_payload = "#{timestamp}.#{raw_body}"
+        expected = OpenSSL::HMAC.hexdigest("SHA256", secret, signed_payload)
+
+        return if ActiveSupport::SecurityUtils.secure_compare(expected, received)
+
+        raise WebhookInbox::SignatureError, "Stripe signature verification failed"
+      end
+    end
+  end
+end

data/lib/webhook_inbox/receiver.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module WebhookInbox
+  module Receiver
+    extend ActiveSupport::Concern
+
+    included do
+      class_attribute :_webhook_provider, instance_accessor: false
+      class_attribute :_webhook_secret_resolver, instance_accessor: false
+    end
+
+    class_methods do
+      # Declare the provider and secret for this controller.
+      #
+      #   receive_from :stripe, secret: -> { ENV["STRIPE_WEBHOOK_SECRET"] }
+      def receive_from(provider, secret:)
+        self._webhook_provider = provider.to_sym
+        self._webhook_secret_resolver = secret
+      end
+    end
+
+    # Run the full receive pipeline:
+    #   1. Verify provider signature (401 on failure)
+    #   2. Store event in DB (200 silent on duplicate)
+    #   3. Enqueue ProcessJob
+    #   4. Respond 200 OK
+    def receive_webhook!
+      provider_name = self.class._webhook_provider
+      raise "No provider declared. Call receive_from :stripe, secret: -> { ... }" unless provider_name
+
+      adapter  = WebhookInbox.provider_for(provider_name)
+      secret   = self.class._webhook_secret_resolver.call
+      raw_body = read_request_body
+
+      verify_signature!(adapter, raw_body, secret) || return
+      store_and_process(adapter, raw_body, provider_name) || return
+
+      head :ok
+    end
+
+    private
+
+    def read_request_body
+      request.body.rewind # Rewind first — middleware may have consumed the body
+      request.body.read
+    end
+
+    def verify_signature!(adapter, raw_body, secret)
+      adapter.verify!(raw_body, request, secret: secret)
+      true
+    rescue WebhookInbox::SignatureError
+      head :unauthorized
+      false
+    end
+
+    def store_and_process(adapter, raw_body, provider_name)
+      event = WebhookInbox::Event.create!(
+        provider: provider_name.to_s,
+        event_id: adapter.event_id(raw_body, request),
+        event_type: adapter.event_type(raw_body, request),
+        payload: raw_body,
+        status: "pending"
+      )
+      WebhookInbox::ProcessJob.set(queue: WebhookInbox.configuration.queue_name)
+                              .perform_later(event.id)
+      true
+    rescue ActiveRecord::RecordNotUnique
+      head :ok # Duplicate delivery — idempotent 200
+      false
+    end
+  end
+end

data/lib/webhook_inbox/rspec/helpers.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "openssl"
+require "json"
+
+module WebhookInbox
+  module RSpecHelpers
+    # Simulate a signed webhook delivery to the given path.
+    # Signs the payload using the provider's scheme so signature verification passes.
+    #
+    # @param provider [Symbol] e.g. :stripe
+    # @param event_type [String] e.g. "customer.subscription.created"
+    # @param payload [Hash] the event payload (will be JSON-encoded)
+    # @param path [String] the route to POST to (default: "/webhooks/#{provider}")
+    # @param event_id [String] override the generated event ID
+    # @param secret [String] the webhook secret (default: "test_secret")
+    def deliver_webhook(provider, event_type, payload: {}, path: nil, event_id: nil, secret: "test_secret")
+      path ||= "/webhooks/#{provider}"
+      headers = build_webhook_headers(provider, event_type, payload, event_id: event_id, secret: secret)
+      post path, params: headers[:body], headers: headers[:headers]
+    end
+
+    private
+
+    def build_webhook_headers(provider, event_type, payload, event_id:, secret:)
+      case provider.to_sym
+      when :stripe
+        build_stripe_headers(event_type, payload, event_id: event_id, secret: secret)
+      else
+        raise ArgumentError, "No RSpec helper for provider: #{provider}"
+      end
+    end
+
+    def build_stripe_headers(event_type, payload, event_id:, secret:)
+      id   = event_id || "evt_test_#{SecureRandom.hex(8)}"
+      body = JSON.generate({ id: id, type: event_type, data: payload })
+      ts   = Time.now.to_i.to_s
+      sig  = OpenSSL::HMAC.hexdigest("SHA256", secret, "#{ts}.#{body}")
+
+      {
+        body: body,
+        headers: {
+          "CONTENT_TYPE" => "application/json",
+          "HTTP_STRIPE_SIGNATURE" => "t=#{ts},v1=#{sig}"
+        }
+      }
+    end
+  end
+end

data/lib/webhook_inbox/rspec.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require "webhook_inbox/rspec/helpers"
+
+RSpec.configure do |config|
+  config.include WebhookInbox::RSpecHelpers, type: :request
+end

data/lib/webhook_inbox/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module WebhookInbox
+  VERSION = "0.1.0"
+end

data/lib/webhook_inbox.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "active_support"
+require "active_support/core_ext/module/attribute_accessors"
+
+require_relative "webhook_inbox/version"
+require_relative "webhook_inbox/configuration"
+require_relative "webhook_inbox/providers/base"
+require_relative "webhook_inbox/providers/stripe"
+
+module WebhookInbox
+  mattr_accessor :configuration
+
+  class SignatureError < StandardError; end
+  class UnknownProviderError < StandardError; end
+
+  PROVIDERS = {
+    stripe: WebhookInbox::Providers::Stripe
+  }.freeze
+
+  class << self
+    def configure
+      self.configuration ||= Configuration.new
+      yield configuration
+    end
+
+    def provider_for(name)
+      klass = PROVIDERS[name.to_sym]
+      raise UnknownProviderError, "Unknown provider: #{name}. Available: #{PROVIDERS.keys.join(', ')}" unless klass
+
+      klass.new
+    end
+  end
+end
+
+require_relative "webhook_inbox/engine" if defined?(Rails::Engine)

data/sig/webhook_inbox.rbs

@@ -0,0 +1,4 @@
+module WebhookInbox
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end