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.

Add this line to your application's Gemfile:

gem "action_hooks"

And then execute:

$ 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.

$ rails generate action_hooks:install

Run the database migrations:

$ rails db:migrate

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.

# 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 = "StripeWebhookJob"

    # 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/hosts
    # source.allowed_hosts = ["127.0.0.1", "10.0.0.1"] # Also aliased as `allowed_ips`
  end
end

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:

$ rails generate action_hooks:webhook stripe

This will create app/jobs/stripe_webhook_job.rb. The background job will receive the ID of the saved ActionHooks::WebhookRequest record:

# 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)
    payload = webhook_request.payload

    case payload["type"]
    when "payment_intent.succeeded"
      # handle payment
    end

    webhook_request.processed!
  rescue => e
    webhook_request.failed!
    raise e
  end
end

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:

$ 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:

# 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

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.

Bug reports and pull requests are welcome on GitHub at https://github.com/alec-c4/action_hooks.

The gem is available as open source under the terms of the MIT License.