How to Receive Plaid Webhooks in Ruby on Rails

Skip CSRF + read request.raw_post for HMAC-friendly handlers

Rails remains the canonical Ruby web framework for SaaS. Its built-in CSRF protection is great for forms but actively blocks webhook handlers — you have to disable it on the webhook route AND read request.raw_post to get the unparsed bytes that HMAC verification needs. This guide walks through the Ruby on Rails setup for Plaid webhooks end to end: capturing the raw body, verifying the signature, handling retries idempotently, and iterating locally without redeploying. Cross-reference the Plaid Webhooks overview for the event catalog and sample payload.

1. Set Up the Ruby on Rails Endpoint

The endpoint needs to do three things, in this order: read the raw body, verify the signature against those exact bytes, and only then parse the JSON for your business logic.

# config/routes.rb
Rails.application.routes.draw do
  post '/webhooks/:service', to: 'webhooks#receive', as: :webhook
end

# app/controllers/webhooks_controller.rb
class WebhooksController < ApplicationController
  # CSRF tokens don't apply to programmatic webhook deliveries.
  skip_before_action :verify_authenticity_token

  def receive
    raw_body = request.raw_post  # raw bytes — NOT parsed by Rails
    signature = request.headers['X-Signature-Header']

    # 1. Verify HMAC over raw_body
    # 2. Parse JSON only after verification passes
    # 3. Process the event idempotently (use the event id as your key)

    event = JSON.parse(raw_body)
    Rails.logger.info "Verified webhook: #{event['type'] || event}"

    head :ok
  end
end

2. Verify the Plaid Signature

Ruby verification

# Gemfile: gem 'jwt', gem 'plaid'
require 'jwt'
require 'base64'

class WebhooksController < ApplicationController
  skip_before_action :verify_authenticity_token, only: [:plaid]

  def plaid
    body = request.raw_post
    token = request.headers['Plaid-Verification'].to_s
    return head :unauthorized if token.empty?

    # Inspect JWT header for kid.
    header_b64 = token.split('.').first
    header = JSON.parse(Base64.urlsafe_decode64(header_b64))
    return head :unauthorized unless header['alg'] == 'ES256'

    # Fetch JWK from Plaid (configure SDK separately).
    plaid_client = Plaid::PlaidApi.new(@plaid_configuration)
    jwk = plaid_client.webhook_verification_key_get(
      Plaid::WebhookVerificationKeyGetRequest.new(key_id: header['kid']),
    ).key

    decoded, = JWT.decode(token, JWT::JWK.import(jwk).public_key, true,
                          { algorithm: 'ES256' })

    # 5-minute replay window.
    return head :unauthorized if (Time.now.to_i - decoded['iat']).abs > 300

    body_hash = OpenSSL::Digest::SHA256.hexdigest(body)
    unless body_hash == decoded['request_body_sha256']
      return head :forbidden
    end
    render json: { ok: true }
  end
end

Wire this verification call into the Ruby on Rails handler from section 1. The pattern is identical across Ruby on Rails versions: read raw body, verify, parse JSON, dispatch.

See Plaid's official signing docs for the canonical reference, or the cross-service signature verification guide for the same pattern in Ruby and other languages.

3. Make the Handler Idempotent

Plaid can — and will — send the same event twice. Network blips, your server returning a 5xx mid-processing, deploy windows: any of these triggers a retry, and your handler will see the same event id again. Build for that on day one rather than chasing duplicate-charge bugs in production.

The simplest pattern is a unique constraint on the event id in your database. The handler does the work inside a transaction, and the insert into the events table is the last step — if a retry arrives, the unique-constraint violation tells you the event already committed and you can return 200 without re-running the side effects.

4. Test Locally Without Deploying

The fastest iteration loop for any webhook handler is: capture a real Plaid event with HookRay, then replay that captured request against your local Ruby on Rails server until the verification + business logic both pass. No need to retrigger the event in Plaid, no need to redeploy.

1. Get a free webhook URL at hookray.com — no signup.
2. Paste the URL into your Plaiddashboard's webhook settings.
3. Trigger a test event. HookRay shows the headers, raw body, and parsed payload in real time.
4. Use HookRay's replay feature to send the captured request against http://localhost:3000/api/webhooks/plaid (or wherever your Ruby on Rails app is listening) — iterate on your code without re-poking the Plaid dashboard.

Deploying the Ruby on Rails Handler

Rails apps run well on long-running containers (Render, Fly.io, Heroku, Kamal-deployed VPS). Avoid hosting Rails as serverless functions for webhook endpoints — boot time is unforgiving and Rails warm-up easily blows past the 5-15 second window most webhook senders give you before retrying.

Need a host that boots quickly enough to absorb webhook bursts? DigitalOcean droplets stay warm, support raw-body proxies cleanly, and avoid the cold-start traps of some serverless runtimes.