action_hooks 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 064ad39bd578ac07aaf40f9bbc3551a7f8134a8543666533c7346782ec38a7d2
+  data.tar.gz: f1f6e53ed1cd91f80ebbea439c765aa7a7ec9cae4a7ff315f3230b51fb92a388
+SHA512:
+  metadata.gz: 29b792245c0630a7542e2189baaf89724090400baed65d26931e7d3fd513bf6f38092868ea9e0e7010b0940dcaa23058367ecde6387394c25c8519aa4990cb59
+  data.tar.gz: b166f6b4be57655cbab8449eba6ed16d9dfe54f8c0eb2449a6362ff24492dc4c7770391fc07da69c832b008e0d477f7b3b8475e1958daf2ebc287dfbd611a557

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2026-03-01
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Alexey Poimtsev
+
+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,119 @@
+# ActionHooks
+
+ActionHooks is a Ruby on Rails engine designed to securely handle incoming webhooks. It standardizes the process of receiving webhooks from various third-party services (like Stripe, GitHub, etc.) by:
+
+1. **Persisting Webhooks:** Saving all incoming requests to the database (`webhook_requests` table) with their payload, source, and processing state before any business logic is executed.
+2. **Security & Verification:** Verifying the authenticity of the webhook via signature validation logic and optionally restricting access by IP address.
+3. **Asynchronous Processing:** Automatically dispatching the saved webhook to a configured background worker (`ActiveJob`) for asynchronous processing.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "action_hooks"
+```
+
+And then execute:
+
+```bash
+$ bundle install
+```
+
+After installing the gem, you need to run the installation generator. This will create the necessary database migration for the `webhook_requests` table and an initializer file.
+
+```bash
+$ rails generate action_hooks:install
+```
+
+Run the database migrations:
+
+```bash
+$ rails db:migrate
+```
+
+## Usage
+
+### 1. Configuration
+
+Configure your webhook sources in the generated initializer (`config/initializers/action_hooks.rb`). Each source represents a third-party service sending webhooks to your application.
+
+```ruby
+# config/initializers/action_hooks.rb
+ActionHooks.configure do |config|
+  config.add_source(:stripe) do |source|
+    # The ActiveJob worker class that will process the webhook
+    source.worker = "StripeWebhookWorker"
+    
+    # Lambda to verify the signature of the incoming request
+    source.verify_signature = ->(request) do
+      payload = request.body.read
+      sig_header = request.env['HTTP_STRIPE_SIGNATURE']
+      # Example using Stripe's library:
+      # Stripe::Webhook::Signature.verify_header(payload, sig_header, ENV['STRIPE_WEBHOOK_SECRET'])
+      true
+    end
+    
+    # Optional: Restrict incoming requests to specific IP addresses
+    # source.allowed_ips = ["127.0.0.1", "10.0.0.1"]
+  end
+end
+```
+
+### 2. Generating a Webhook Controller
+
+To create an endpoint for a configured source, use the webhook generator. Pass the name of the source as an argument:
+
+```bash
+$ rails generate action_hooks:webhook stripe
+```
+
+This will:
+1. Create a controller at `app/controllers/stripe_webhooks_controller.rb`.
+2. Add a route to `config/routes.rb` (e.g., `post "webhooks/stripe", to: "stripe_webhooks#create"`).
+
+The generated controller includes `ActionHooks::WebhookControllerBehavior`, which handles everything from skipping CSRF verification, verifying the IP and signature, saving the request to the database, and enqueueing your worker.
+
+### 3. Processing the Webhook
+
+Create the worker class that you specified in your configuration. The worker will receive the ID of the `ActionHooks::WebhookRequest` record.
+
+```ruby
+# app/jobs/stripe_webhook_worker.rb
+class StripeWebhookWorker < ApplicationJob
+  queue_as :default
+
+  def perform(webhook_request_id)
+    webhook_request = ActionHooks::WebhookRequest.find(webhook_request_id)
+    
+    # Access the parsed JSON payload
+    payload = webhook_request.payload
+    
+    # Process the payload...
+    if payload['type'] == 'payment_intent.succeeded'
+      # Do something
+    end
+    
+    # Update the state of the webhook request when done
+    webhook_request.processed!
+  rescue => e
+    # Mark as failed if something goes wrong
+    webhook_request.failed!
+    raise e
+  end
+end
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. 
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/alec-c4/action_hooks.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/action_hooks/configuration.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module ActionHooks
+  class SourceNotDefinedError < StandardError; end
+
+  class Source
+    attr_accessor :name, :worker, :verify_signature, :allowed_ips
+
+    def initialize(name)
+      @name = name
+      @verify_signature = ->(_request) { true }
+      @allowed_ips = []
+    end
+  end
+
+  class Configuration
+    def initialize
+      @sources = {}
+    end
+
+    def add_source(name)
+      source = Source.new(name)
+      yield(source) if block_given?
+      @sources[name.to_sym] = source
+    end
+
+    def source(name)
+      @sources.fetch(name.to_sym)
+    rescue KeyError
+      raise SourceNotDefinedError, "Source :#{name} is not defined in ActionHooks configuration"
+    end
+  end
+
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+  end
+end

data/lib/action_hooks/engine.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require "rails/engine"
+
+module ActionHooks
+  class Engine < ::Rails::Engine
+    isolate_namespace ActionHooks
+  end
+end

data/lib/action_hooks/version.rb

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

data/lib/action_hooks/webhook_controller_behavior.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module ActionHooks
+  module WebhookControllerBehavior
+    extend ActiveSupport::Concern
+
+    included do
+      # Skip CSRF since webhooks are typically APIs
+      skip_before_action :verify_authenticity_token, raise: false if respond_to?(:skip_before_action)
+
+      before_action :verify_webhook_ip!
+      before_action :verify_webhook_signature!
+    end
+
+    def create
+      payload = parse_webhook_payload
+
+      webhook_request = ActionHooks::WebhookRequest.create!(
+        source: webhook_source_name.to_s,
+        payload: payload,
+        state: :pending
+      )
+
+      worker_class = webhook_source_config.worker
+      worker_class&.constantize&.perform_later(webhook_request.id)
+
+      head :ok
+    end
+
+    private
+
+    def webhook_source_name
+      # To be overridden or inferred by the controller
+      self.class.name.sub(/WebhooksController$/, "").underscore
+    end
+
+    def webhook_source_config
+      ActionHooks.configuration.source(webhook_source_name)
+    end
+
+    def verify_webhook_ip!
+      allowed_ips = webhook_source_config.allowed_ips
+      return if allowed_ips.empty?
+
+      unless allowed_ips.include?(request.remote_ip)
+        head :forbidden
+      end
+    end
+
+    def verify_webhook_signature!
+      unless webhook_source_config.verify_signature.call(request)
+        head :unauthorized
+      end
+    end
+
+    def parse_webhook_payload
+      if request.content_type == "application/json"
+        JSON.parse(request.body.read).tap do
+          request.body.rewind
+        end
+      else
+        request.parameters.except(:controller, :action).to_unsafe_h
+      end
+    rescue JSON::ParserError
+      {}
+    end
+  end
+end

data/lib/action_hooks.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require_relative "action_hooks/version"
+require_relative "action_hooks/configuration"
+
+module ActionHooks
+  class Error < StandardError; end
+end
+require "action_hooks/engine"
+require "action_hooks/webhook_controller_behavior"

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

@@ -0,0 +1,26 @@
+require "rails/generators"
+require "rails/generators/active_record"
+
+module ActionHooks
+  module Generators
+    class InstallGenerator < ::Rails::Generators::Base
+      include ::Rails::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Installs ActionHooks migration and initializer"
+
+      def self.next_migration_number(dirname)
+        ::ActiveRecord::Generators::Base.next_migration_number(dirname)
+      end
+
+      def create_migration_file
+        migration_template "create_webhook_requests.rb.erb", "db/migrate/create_webhook_requests.rb"
+      end
+
+      def create_initializer_file
+        template "action_hooks.rb", "config/initializers/action_hooks.rb"
+      end
+    end
+  end
+end

data/lib/generators/action_hooks/install/templates/action_hooks.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+ActionHooks.configure do |config|
+  # Example Configuration for Stripe
+  # config.add_source(:stripe) do |source|
+  #   source.worker = "StripeWebhookWorker" # Ensure you have this ActiveJob defined
+  #
+  #   # Verify signature logic (returns a boolean)
+  #   source.verify_signature = ->(request) do
+  #     # Example:
+  #     # payload = request.body.read
+  #     # sig_header = request.env['HTTP_STRIPE_SIGNATURE']
+  #     # Stripe::Webhook::Signature.verify_header(payload, sig_header, 'whsec_...', tolerance: Stripe::Webhook::DEFAULT_TOLERANCE)
+  #     true
+  #   end
+  #
+  #   # Optional: IP allowlist
+  #   # source.allowed_ips = ["127.0.0.1", "10.0.0.1"]
+  # end
+end

data/lib/generators/action_hooks/install/templates/create_webhook_requests.rb.erb

@@ -0,0 +1,14 @@
+class CreateWebhookRequests < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+    create_table :webhook_requests, id: :uuid do |t|
+      t.jsonb :payload, default: {}, null: false
+      t.string :source, null: false
+      t.integer :state, null: false, default: 0
+
+      t.timestamps
+    end
+
+    add_index :webhook_requests, :source
+    add_index :webhook_requests, :state
+  end
+end

data/lib/generators/action_hooks/webhook/templates/controller.rb.erb

@@ -0,0 +1,9 @@
+class <%= class_name %>WebhooksController < ApplicationController
+  include ActionHooks::WebhookControllerBehavior
+
+  private
+
+  def webhook_source_name
+    :<%= file_name %>
+  end
+end

data/lib/generators/action_hooks/webhook/webhook_generator.rb

@@ -0,0 +1,18 @@
+require "rails/generators"
+
+module ActionHooks
+  module Generators
+    class WebhookGenerator < ::Rails::Generators::NamedBase
+      source_root File.expand_path("templates", __dir__)
+      desc "Creates a webhook controller for a given source and adds its route."
+
+      def create_controller_file
+        template "controller.rb.erb", "app/controllers/#{file_name}_webhooks_controller.rb"
+      end
+
+      def add_route
+        route %(post "webhooks/#{file_name}", to: "#{file_name}_webhooks#create")
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,156 @@
+--- !ruby/object:Gem::Specification
+name: action_hooks
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Alexey Poimtsev
+bindir: exe
+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.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rspec-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: appraisal
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Save all incoming webhooks to the database, dispatch them to background
+  workers, and verify request signatures or IPs.
+email:
+- alexey.poimtsev@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/action_hooks.rb
+- lib/action_hooks/configuration.rb
+- lib/action_hooks/engine.rb
+- lib/action_hooks/version.rb
+- lib/action_hooks/webhook_controller_behavior.rb
+- lib/generators/action_hooks/install/install_generator.rb
+- lib/generators/action_hooks/install/templates/action_hooks.rb
+- lib/generators/action_hooks/install/templates/create_webhook_requests.rb.erb
+- lib/generators/action_hooks/webhook/templates/controller.rb.erb
+- lib/generators/action_hooks/webhook/webhook_generator.rb
+homepage: https://github.com/alec-c4/action_hooks
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/alec-c4/action_hooks
+  source_code_uri: https://github.com/alec-c4/action_hooks
+  changelog_uri: https://github.com/alec-c4/action_hooks/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.7
+specification_version: 4
+summary: A Ruby gem for handling incoming webhooks securely.
+test_files: []