action_hooks 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 064ad39bd578ac07aaf40f9bbc3551a7f8134a8543666533c7346782ec38a7d2
-  data.tar.gz: f1f6e53ed1cd91f80ebbea439c765aa7a7ec9cae4a7ff315f3230b51fb92a388
+  metadata.gz: 284686e350568c9e92b85744b29ad6eb114657ae8872464292020edd97ed32ae
+  data.tar.gz: 3f226eff09c69f48a0430bcedd6d8d6583ae4bf0c4cb359de9f13f833d4ce8e2
 SHA512:
-  metadata.gz: 29b792245c0630a7542e2189baaf89724090400baed65d26931e7d3fd513bf6f38092868ea9e0e7010b0940dcaa23058367ecde6387394c25c8519aa4990cb59
-  data.tar.gz: b166f6b4be57655cbab8449eba6ed16d9dfe54f8c0eb2449a6362ff24492dc4c7770391fc07da69c832b008e0d477f7b3b8475e1958daf2ebc287dfbd611a557
+  metadata.gz: 11209c21b103ca1e42b2970dc2d9bed285ac0b9b032824303a418d02da6850c1db36319aaf6f4fa30ee3b6eec7d815a066bd1ae091d9d033ad44dafcefdf88ca
+  data.tar.gz: 1efbaf2b0533019d20e3d00f52b348bfa3f11a44b9880fd9676136575ebcaab2ce563a1363b92661552706a1cba88350d6feb14b7d4a11fe97fa5365de7f6bd7

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 ## [Unreleased]
 
+## [0.2.0] - 2026-03-02
+
+- Refactored ActionHooks to operate purely as middleware. It now automatically mounts `POST /webhooks/:source` without needing any generated configuration route handling.
+- Re-designed `rails g action_hooks:webhook` generator to create only Jobs by default. A new `--controller` flag is available for customized business logic needs.
+
 ## [0.1.0] - 2026-03-01
 
 - Initial release

data/README.md

@@ -36,15 +36,15 @@ $ rails db:migrate
 
 ### 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.
+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. ActionHooks automatically mounts a catch-all route `POST /webhooks/:source`, so configuring a source is enough to start receiving requests.
 
 ```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"
-    
+    source.worker = "StripeWebhookJob"
+
     # Lambda to verify the signature of the incoming request
     source.verify_signature = ->(request) do
       payload = request.body.read
@@ -53,60 +53,80 @@ ActionHooks.configure do |config|
       # 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"]
+
+    # Optional: Restrict incoming requests to specific IP addresses/hosts
+    # source.allowed_hosts = ["127.0.0.1", "10.0.0.1"] # Also aliased as `allowed_ips`
   end
 end
 ```
 
-### 2. Generating a Webhook Controller
+### 2. Generating a Job
 
-To create an endpoint for a configured source, use the webhook generator. Pass the name of the source as an argument:
+By default, an incoming webhook is authenticated, persisted, and handed over to a background job. You can easily generate a job template for your source:
 
 ```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.
+This will create `app/jobs/stripe_webhook_job.rb`. The background job will receive the ID of the saved `ActionHooks::WebhookRequest` record:
 
 ```ruby
-# app/jobs/stripe_webhook_worker.rb
-class StripeWebhookWorker < ApplicationJob
+# app/jobs/stripe_webhook_job.rb
+class StripeWebhookJob < 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
+
+    case payload["type"]
+    when "payment_intent.succeeded"
+      # handle payment
     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
 ```
 
+### 3. Custom Controller (Optional)
+
+If your webhook processing requires complex synchronous logic before placing the job into the queue, you can generate a custom controller using the `--controller` flag:
+
+```bash
+$ rails generate action_hooks:webhook stripe --controller
+```
+
+This generates:
+
+- A job: `app/jobs/stripe_webhook_job.rb` (unless `--skip-job` is provided)
+- A controller: `app/controllers/webhooks/stripe_controller.rb`
+- A specific route mapping in `config/routes.rb`
+
+Your custom controller will inherit from `ActionHooks::WebhookController`. The parent controller handles persistence, IP checks, and signature verification, while your controller can focus just on the business logic inside the `process_webhook` hook:
+
+```ruby
+# app/controllers/webhooks/stripe_controller.rb
+class Webhooks::StripeController < ActionHooks::WebhookController
+  private
+
+  def webhook_source_name
+    :stripe
+  end
+
+  def process_webhook(webhook_request)
+    # Business logic here.
+    # The default behavior inside `process_webhook` is to enqueue the configured background job.
+  end
+end
+```
+
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. 
+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).
 

data/lib/action_hooks/configuration.rb

@@ -5,6 +5,8 @@ module ActionHooks
 
   class Source
     attr_accessor :name, :worker, :verify_signature, :allowed_ips
+    alias_method :allowed_hosts, :allowed_ips
+    alias_method :allowed_hosts=, :allowed_ips=
 
     def initialize(name)
       @name = name

data/lib/action_hooks/engine.rb

@@ -5,5 +5,13 @@ require "rails/engine"
 module ActionHooks
   class Engine < ::Rails::Engine
     isolate_namespace ActionHooks
+
+    initializer "action_hooks.routes" do |app|
+      app.routes.append do
+        post "webhooks/:source",
+          to: "action_hooks/webhooks#create",
+          constraints: {source: /[a-z0-9_]+/}
+      end
+    end
   end
 end

data/lib/action_hooks/version.rb

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

data/lib/action_hooks/webhook_controller_behavior.rb

@@ -10,28 +10,21 @@ module ActionHooks
 
       before_action :verify_webhook_ip!
       before_action :verify_webhook_signature!
+      before_action :persist_webhook_request!
     end
 
-    def create
-      payload = parse_webhook_payload
+    private
 
-      webhook_request = ActionHooks::WebhookRequest.create!(
+    def persist_webhook_request!
+      @webhook_request = ActionHooks::WebhookRequest.create!(
         source: webhook_source_name.to_s,
-        payload: payload,
+        payload: parse_webhook_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
+      raise NotImplementedError, "You must define `#webhook_source_name` in your webhook controller."
     end
 
     def webhook_source_config

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

@@ -1,7 +1,16 @@
 class CreateWebhookRequests < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
   def change
-    create_table :webhook_requests, id: :uuid do |t|
-      t.jsonb :payload, default: {}, null: false
+    <%-
+      json_type = (ActiveRecord::Base.connection.adapter_name.downcase == "postgresql") ? :jsonb : :json
+      
+      supports_uuid = if ActiveRecord::Base.connection.respond_to?(:supports_uuid?) 
+        ActiveRecord::Base.connection.supports_uuid? # PostgreSQL
+      else 
+        false # Defaults for others like SQLite, typical MySQL setups unless explicitly configured
+      end
+    -%>
+    create_table :webhook_requests<%= supports_uuid ? ", id: :uuid" : "" %> do |t|
+      t.<%= json_type %> :payload, default: {}, null: false
       t.string :source, null: false
       t.integer :state, null: false, default: 0
 

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

@@ -1,9 +1,12 @@
-class <%= class_name %>WebhooksController < ApplicationController
-  include ActionHooks::WebhookControllerBehavior
-
+class Webhooks::<%= class_name %>Controller < ActionHooks::WebhookController
   private
 
   def webhook_source_name
     :<%= file_name %>
   end
+
+  def process_webhook(webhook_request)
+    # Business logic here.
+    # @webhook_request is also available as an instance variable.
+  end
 end

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

@@ -0,0 +1,19 @@
+class <%= class_name %>WebhookJob < ApplicationJob
+  queue_as :default
+
+  def perform(webhook_request_id)
+    webhook_request = ActionHooks::WebhookRequest.find(webhook_request_id)
+    payload = webhook_request.payload
+
+    # TODO: handle payload
+    # case payload["type"]
+    # when "example.event"
+    #   # handle event
+    # end
+
+    webhook_request.processed!
+  rescue => e
+    webhook_request.failed!
+    raise e
+  end
+end

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

@@ -1,17 +1,31 @@
+# frozen_string_literal: true
+
 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."
+      desc "Creates a webhook job (and optionally a controller) for a given source."
+
+      class_option :controller, type: :boolean, default: false,
+        desc: "Also generate a custom controller for business logic"
+      class_option :skip_job, type: :boolean, default: false,
+        desc: "Skip job generation"
+
+      def create_job_file
+        return if options[:skip_job]
+        template "job.rb.erb", "app/jobs/#{file_name}_webhook_job.rb"
+      end
 
       def create_controller_file
-        template "controller.rb.erb", "app/controllers/#{file_name}_webhooks_controller.rb"
+        return unless options[:controller]
+        template "controller.rb.erb", "app/controllers/webhooks/#{file_name}_controller.rb"
       end
 
       def add_route
-        route %(post "webhooks/#{file_name}", to: "#{file_name}_webhooks#create")
+        return unless options[:controller]
+        route %(post "webhooks/#{file_name}", to: "webhooks/#{file_name}#create")
       end
     end
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: action_hooks
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Alexey Poimtsev
@@ -127,6 +127,7 @@ files:
 - 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/templates/job.rb.erb
 - lib/generators/action_hooks/webhook/webhook_generator.rb
 homepage: https://github.com/alec-c4/action_hooks
 licenses: