stripe-webhook-integration

Stripe Webhook Integration

Stripe webhooks are the most common webhook integration in Rails. Get them right: signature + timestamp verification, idempotency by event.id, handle the events you actually need (not every event in the catalog), retry safely.

The opinion

Use Stripe::Webhook.construct_event — signature + timestamp covered in one call. Persist a WebhookEvent for idempotency. Enqueue a job for actual processing. Handle only the events your business needs; ignore the rest. Separate test-mode and live-mode webhook secrets.

The event types you actually handle

HANDLED_EVENTS = %w[
  payment_intent.succeeded
  payment_intent.payment_failed
  charge.refunded
  customer.subscription.created
  customer.subscription.updated
  customer.subscription.deleted
  invoice.payment_succeeded
  invoice.payment_failed
  customer.created
  checkout.session.completed
]

Everything else: log + skip. Don't reach for events you don't have a business action for.

Core patterns

Pattern 1: The controller

# app/controllers/webhooks/stripe_controller.rb
class Webhooks::StripeController < Webhooks::BaseController
  HANDLED_EVENTS = %w[
    payment_intent.succeeded payment_intent.payment_failed
    charge.refunded
    customer.subscription.created customer.subscription.updated customer.subscription.deleted
    invoice.payment_succeeded invoice.payment_failed
    checkout.session.completed
  ]

  def receive
    event = Stripe::Webhook.construct_event(
      raw_body,
      request.headers["Stripe-Signature"],
      Rails.application.credentials.stripe_webhook_secret
    )

    return head(:ok) unless HANDLED_EVENTS.include?(event.type)

    handle_idempotent(event.id, "stripe") do |webhook|
      webhook.update!(event_type: event.type, payload: event.to_hash)
      ProcessStripeEventJob.perform_later(webhook.id)
    end

    head(:ok)
  rescue Stripe::SignatureVerificationError
    head(:bad_request)
  rescue JSON::ParserError
    head(:bad_request)
  end
end