Vindi Rails Integrations

Leia em Português (README.pt-BR.md)

An extension gem for the vindi-rails core SDK, providing backend integrations such as automatic ActiveRecord model synchronization, webhook controller endpoints, asynchronous processing jobs, and verification Rake tasks.

Add this line to your application's Gemfile:

gem 'vindi-rails-integrations'

To handle incoming webhook events asynchronously with built-in access token verification:

bundle exec rails generate vindi:webhook

This generates:

• Vindi::WebhooksController (app/controllers/vindi/webhooks_controller.rb)
• Vindi::WebhookJob (app/jobs/vindi/webhook_job.rb)

Configure your webhook access token in your environment files:

ENV["VINDI_WEBHOOK_TOKEN"] = "YOUR_SECURE_TOKEN"

Instead of processing all webhook events inside a single WebhookJob, you can generate modular event-specific handlers:

bundle exec rails generate vindi:webhook_handler subscription_canceled

This generates:

• Vindi::Webhooks::BaseHandler (app/services/vindi/webhooks/base_handler.rb) - created once if missing.
• Vindi::Webhooks::SubscriptionCanceledHandler (app/services/vindi/webhooks/subscription_canceled_handler.rb)

The main WebhookJob automatically detects and forwards the event payload to matching handlers (e.g. Vindi::Webhooks::SubscriptionCanceledHandler for subscription_canceled events) with safe fallback to legacy inline handlers.

To automatically synchronize local models (e.g. User) with Vindi Customers:

bundle exec rails generate vindi:sync User

This generates a database migration to add vindi_customer_id and includes the Vindi::Synchronizable concern into your model.

To prevent network latencies or API downtime from blocking your local database transactions, you can enable the Outbox pattern. This saves the synchronization tasks locally in a database table during the transaction, and processes them asynchronously.

1. Generate the Outbox migration:

   bundle exec rails generate vindi:outbox
   bundle exec rails db:migrate

2. Enable Outbox in your initializer:

   Vindi.configure do |config|
     config.use_outbox = true
   end

3. Processing: The Vindi::ProcessPendingSyncsJob is automatically queued to run in the background after the model commits. You can also run it manually or schedule it:

   Vindi::ProcessPendingSyncsJob.perform_later

• bundle exec rake vindi:status: Verifies API configuration, environment, credentials (safely masked), and tests connection to Vindi.
• bundle exec rake vindi:audit model=User: Reconciles database records against the Vindi API to detect missing or mismatched records.
• bundle exec rake vindi:test_webhook event=bill_paid: Simulates sending a webhook event payload directly to your local endpoint.

To run the Minitest suite:

bundle exec rake test