Ruby on Rails SDK

sentriq-rails is the Rails integration for the Ruby SDK — an installer generator and a webhook-signature-verification controller concern, built on top of the framework-neutral sentriq gem. It never duplicates that gem's HTTP transport or webhook cryptography. Requires Ruby 3.1+ and Rails 7.1, 7.2, 8.0, or 8.1 (see § Version compatibility — Rails 8.x itself requires Ruby >= 3.2). Not yet published to RubyGems.org — install via a local path or a locally-built .gem file until a release process exists.

Install

gem install sentriq-rails

Not yet resolvable from RubyGems.org — see § Publication status below for the real, current install path.

Configure

rails generate sentriq:install

Creates config/initializers/sentriq.rb:

Sentriq::Rails.configure do |config|
  config.secret_key = ENV.fetch("SENTRIQ_SECRET_KEY", nil)
  config.api_url = ENV.fetch("SENTRIQ_API_URL", nil)
  config.webhook_secret = ENV.fetch("SENTRIQ_WEBHOOK_SECRET", nil)
end

Usage

event = Sentriq::Rails.client.events.retrieve("evt_XXXXXXXXXXXXXXXXXXXX")
Sentriq::Rails.client.events.submit_outcome("evt_XXXXXXXXXXXXXXXXXXXX", label: :legitimate)

Sentriq::Rails.client is a memoized, thread-safe singleton built once from Sentriq::Rails.configuration — a module-level configuration object, not a Rails DI-container binding (Ruby/Rails has no equivalent IoC-container convention the way Laravel does). Every resource the base gem exposes is reachable the same way: Sentriq::Rails.client.devices/.accounts/.risk/.network/.webhooks.

Webhook verification

class WebhooksController < ApplicationController
  include Sentriq::Rails::VerifiesWebhook

  verify_sentriq_webhook! only: [:create]

  def create
    # the request has already been verified
  end
end

A controller before_action, not a Rack middleware — the idiomatic Rails building block for "verify one specific route," and it works identically in ActionController::API and ActionController::Base apps. Delegates the actual HMAC-SHA256 check to Sentriq::Resources::Webhooks#verify_signature — never reimplemented. For more than one webhook endpoint, pass secret: (a String or a zero-arg callable):

verify_sentriq_webhook! secret: -> { Rails.application.credentials.sentriq_billing_webhook_secret },
                        only: [:create]

Response codes

Thread safety

Sentriq::Rails.client is built once, under a Mutex, the first time it's requested — every later call (from any thread) returns the same instance, proven by a dedicated spec (32 threads, first concurrent access). Safe to share across Puma/Sidekiq workers.

Version compatibility

Ruby 3.1+, Rails >= 7.1, < 9.0 (7.1, 7.2, 8.0, and 8.1) — proven across every Ruby(3.1–3.4) × Rails combination the Ruby floor allows (14 combinations; Rails 8.x itself requires Ruby >= 3.2, so Ruby 3.1 + Rails 8.x is not possible at the dependency level). A real Rails 8.1.x require-ordering bug (inside railties itself) was found, root-caused, and fixed in this gem — see docs/architecture/RAILS_SDK.md § Rails 8.x compatibility for the full reproduction and matrix.

Publication status

Not published to RubyGems.org — no release process exists for this gem yet. Reference it (and the base sentriq gem) via path: Gemfile entries from a checkout of this repository, or build and install local .gem files.