Add support for Stripe webhooks

We set up the backbone to support Stripe webhook [1] events. There're two
different use cases:

- Users want to listen to certain webhook events. They'll need to add
  their names in a `webhook_events` setting.
- This extension code makes internal use of some of them. That's
  something programmed, and when the time comes, we'll need to add the
  event names in the `SolidusStripe::Webhook::Event::CORE_EVENTS`
  constant.

A new `POST /webhooks` endpoint exists to support the integration. Users
must also configure a `solidus_stripe.webhook_endpoint_secret` Rails
credential to validate the incoming events [2]. There's also a
`webhook_signature_tolerance` setting to change the default number of
seconds while a signature is valid [3].

When an incoming webhook arrives, a matching `Spree::Bus` event
prepended with `stripe.` is published. Therefore, all the usual
techniques in Solidus's pub/sub system [4] are allowed.

[1] - https://stripe.com/docs/webhooks
[2] - https://stripe.com/docs/webhooks/signatures
[3] - https://stripe.com/docs/webhooks/signatures#replay-attacks
[4] - https://guides.solidus.io/customization/subscribing-to-events

Author: waiting-for-dev

README.md

@@ -37,9 +37,92 @@ Bundle your dependencies and run the installation generator:
 bin/rails generate solidus_stripe:install
 ```
 
+### Webhooks
+
+This library makes use of some [Stripe
+webhooks](https://stripe.com/docs/webhooks).
+
+On development, you can [test them by using Stripe CLI](https://stripe.com/docs/webhooks/test).
+
+Before going to production, you'll need to [register the
+`/solidus_stripe/webhooks` endpoint with
+Stripe](https://stripe.com/docs/webhooks/go-live), and make sure to subscribe
+to the following events:
+
+[TBD]
+
+In both environments, you'll need to create a
+`solidus_stripe.webhook_endpoint_secret` credential with [the webhook signing
+secret](https://stripe.com/docs/webhooks/signatures):
+
+```bash
+# For development, add `--environment development`
+bin/rails credentials:edit
+```
+
+```yaml
+# config/credentials.yml.enc
+solidus_stripe:
+  webhook_endpoint_secret: "whsec_..."
+```
+
 ## Usage
 
-<!-- Explain how to use your extension once it's been installed. -->
+### Custom webhooks
+
+You can also use [Stripe webhooks](https://stripe.com/docs/webhooks) to trigger
+custom actions in your application.
+
+First, you need to register the event you want to listen to, both [in
+Stripe](https://stripe.com/docs/webhooks/go-live) and in your application:
+
+```ruby
+# config/initializers/solidus_stripe.rb
+SolidusStripe.configure do |config|
+  config.webhook_events = %i[charge.succeeded]
+end
+```
+
+That will register a new `:"stripe.charge.succeeded"` event in the [Solidus
+bus](https://guides.solidus.io/customization/subscribing-to-events). The
+Solidus event will be published whenever a matching incoming webhook event is
+received. You can subscribe to it as regular:
+
+```ruby
+# app/subscribers/update_account_balance_subscriber.rb
+class UpdateAccountBalanceSubscriber
+  include Omnes::Subscriber
+
+  handle :"stripe.charge.succeeded", with: :call
+
+  def call(event)
+    # ...
+  end
+end
+
+# config/initializers/solidus_stripe.rb
+# ...
+Rails.application.config.to_prepare do
+  UpdateAccountBalanceSubscriber.new.subscribe_to(Spree::Bus)
+end
+```
+
+The passed event object is a thin wrapper around the [Stripe
+event](https://www.rubydoc.info/gems/stripe/Stripe/Event) and will
+delegate all methods to it. It can also be used in async [
+adapters](https://github.com/nebulab/omnes#adapters), which is recommended as
+otherwise the response to Stripe will be delayed until subscribers are done.
+
+You can also configure the signature verification tolerance in seconds (it
+defaults to the [same value as Stripe
+default](https://stripe.com/docs/webhooks/signatures#replay-attacks)):
+
+```ruby
+# config/initializers/solidus_stripe.rb
+SolidusStripe.configure do |config|
+  config.webhook_signature_tolerance = 150
+end
+```
 
 ## Development
 

app/controllers/solidus_stripe/webhooks_controller.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "solidus_stripe/webhook/event"
+require "stripe"
+
+module SolidusStripe
+  class WebhooksController < Spree::BaseController
+    SIGNATURE_HEADER = "HTTP_STRIPE_SIGNATURE"
+
+    skip_before_action :verify_authenticity_token, only: :create
+
+    respond_to :json
+
+    def create
+      request.body.read
+        .then { |payload| Stripe::Webhook.construct_event(payload, signature_header, secret, tolerance: tolerance) }
+        .then { |stripe_event| SolidusStripe::Webhook::Event.new(stripe_event: stripe_event) }
+        .then { |event| Spree::Bus.publish(event) }
+
+      head :ok
+    rescue Stripe::SignatureVerificationError, JSON::ParserError
+      head :bad_request
+    end
+
+    private
+
+    def signature_header
+      request.headers[SIGNATURE_HEADER]
+    end
+
+    def secret
+      Rails.application.credentials.solidus_stripe[:webhook_endpoint_secret]
+    end
+
+    def tolerance
+      SolidusStripe.configuration.webhook_signature_tolerance
+    end
+  end
+end

config/routes.rb

@@ -2,4 +2,5 @@
 
 SolidusStripe::Engine.routes.draw do
   resources :payment_intents, only: :create
+  resources :webhooks, only: :create, format: false
 end

lib/solidus_stripe/configuration.rb

@@ -1,10 +1,24 @@
 # frozen_string_literal: true
 
+require "stripe/webhook"
+
 module SolidusStripe
   class Configuration
-    # Define here the settings for this extension, e.g.:
-    #
-    # attr_accessor :my_setting
+    # @!attribute [rw] webhook_events
+    #  @return [Array<Symbol>] stripe events to handle. You also need to
+    #  register them in the Stripe dashboard. For an event `:foo`, a matching
+    #  `:"stripe.foo"` event will be registered in {Spree::Bus}.
+    attr_accessor :webhook_events
+
+    # @!attribute [rw] webhook_signature_tolerance
+    #  @return [Integer] number of seconds while a webhook event is valid after
+    #  its creation. Defaults to {Stripe::Webhook::DEFAULT_TOLERANCE}.
+    attr_accessor :webhook_signature_tolerance
+
+    def initialize
+      @webhook_events = []
+      @webhook_signature_tolerance = Stripe::Webhook::DEFAULT_TOLERANCE
+    end
   end
 
   class << self

lib/solidus_stripe/engine.rb

@@ -14,6 +14,16 @@ class Engine < Rails::Engine
       app.config.spree.payment_methods << 'SolidusStripe::PaymentMethod'
     end
 
+    initializer "solidus_stripe.pub_sub", after: "spree.core.pub_sub" do |app|
+      app.reloader.to_prepare do
+        require "solidus_stripe/webhook/event"
+        SolidusStripe::Webhook::Event.register(
+          user_events: SolidusStripe.configuration.webhook_events,
+          bus: Spree::Bus
+        )
+      end
+    end
+
     # use rspec for tests
     config.generators do |g|
       g.test_framework :rspec

lib/solidus_stripe/webhook/event.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module SolidusStripe
+  module Webhook
+    # Omnes event wrapping a Stripe event.
+    #
+    # All unknown methods are delegated to the wrapped Stripe event.
+    #
+    # @see Stripe::Event
+    class Event
+      include Omnes::Event
+
+      # TBD
+      CORE_EVENTS = Set[*%i[]].freeze
+      private_constant :CORE_EVENTS
+
+      # @api private
+      def self.register(user_events:, bus:, core_events: CORE_EVENTS)
+        (core_events + user_events).each do |event|
+          bus.register(:"stripe.#{event}")
+        end
+      end
+
+      attr_reader :omnes_event_name
+
+      # @api private
+      def initialize(stripe_event:)
+        @stripe_event = stripe_event
+        @omnes_event_name = :"stripe.#{stripe_event.type}"
+      end
+
+      # Serializable representation of the event.
+      #
+      # Ready to be consumed by async Omnes adapters, like
+      # {Omnes::Subscriber::Adapter::ActiveJob} or
+      # {Omnes::Subscriber::Adapter::Sidekiq}.
+      #
+      # @return [Hash<String, Object>]
+      def payload
+        @stripe_event.as_json
+      end
+
+      private
+
+      def method_missing(method_name, ...)
+        @stripe_event.send(method_name, ...)
+      end
+
+      def respond_to_missing?(...)
+        @stripe_event.respond_to?(...)
+      end
+    end
+  end
+end

spec/lib/solidus_stripe/configuration_spec.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require "solidus_stripe_spec_helper"
+
+RSpec.describe SolidusStripe::Configuration do
+  describe "#initialize" do
+    it "defaults webhook events to empty" do
+      expect(described_class.new.webhook_events).to eq([])
+    end
+
+    it "defaults webhook signature tolerance to stripe's default" do
+      expect(described_class.new.webhook_signature_tolerance).to eq(Stripe::Webhook::DEFAULT_TOLERANCE)
+    end
+  end
+end

spec/lib/solidus_stripe/webhook/event_spec.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require "solidus_stripe_spec_helper"
+require "solidus_stripe/webhook/event"
+require "omnes/bus"
+
+RSpec.describe SolidusStripe::Webhook::Event do
+  let(:charge_suceeded_event) do
+    Stripe::Event.construct_from(
+      SolidusStripe::WebhookFixtures.charge_succeeded
+    )
+  end
+
+  describe ".register" do
+    it "registers core events prepending with 'stripe'" do
+      bus = Omnes::Bus.new
+
+      described_class.register(bus: bus, core_events: %i[foo], user_events: [])
+
+      expect(bus.registry.registered?(:"stripe.foo")).to be(true)
+    end
+
+    it "registers user events prepending with 'stripe'" do
+      bus = Omnes::Bus.new
+
+      described_class.register(bus: bus, user_events: %i[foo])
+
+      expect(bus.registry.registered?(:"stripe.foo")).to be(true)
+    end
+  end
+
+  describe "#initialize" do
+    it "sets the omnes_event_name from the type field" do
+      event = described_class.new(stripe_event: charge_suceeded_event)
+
+      expect(event.omnes_event_name).to be(:"stripe.charge.succeeded")
+    end
+
+    it "delegates all other methods to the stripe event" do
+      event = described_class.new(stripe_event: charge_suceeded_event)
+
+      expect(event.type).to eq("charge.succeeded")
+    end
+  end
+
+  describe "#payload" do
+    it "returns Hash representation" do
+      event = described_class.new(stripe_event: charge_suceeded_event)
+
+      expect(event.payload).to be_a(Hash)
+    end
+
+    it "uses strings for the hash keys" do
+      event = described_class.new(stripe_event: charge_suceeded_event)
+
+      expect(event.payload.keys).to include("type")
+    end
+  end
+end

spec/requests/solidus_stripe/webhooks_controller_spec.rb

@@ -0,0 +1,79 @@
+require "solidus_stripe_spec_helper"
+
+RSpec.describe SolidusStripe::WebhooksController, type: :request do
+  # rubocop:disable RSpec/MultipleMemoizedHelpers
+  describe "POST /create" do
+    let(:timestamp) { Time.zone.now }
+    let(:secret) { "whsec_123" }
+    let(:signature) { Stripe::Webhook::Signature.compute_signature(timestamp, payload, secret) }
+    let(:signature_header) { Stripe::Webhook::Signature.generate_header(timestamp, signature) }
+    let(:signature_header_key) { described_class::SIGNATURE_HEADER }
+
+    before do
+      allow(Rails.application.credentials).to receive(:solidus_stripe).and_return({ webhook_endpoint_secret: secret })
+    end
+
+    context "when the request is valid" do
+      let(:payload) { JSON.generate(SolidusStripe::WebhookFixtures.charge_succeeded) }
+
+      around do |example|
+        if Spree::Bus.registry.registered?(:"stripe.charge.succeeded")
+          example.run
+        else
+          Spree::Bus.register(:"stripe.charge.succeeded")
+          example.run
+          Spree::Bus.registry.unregister(:"stripe.charge.succeeded")
+        end
+      end
+
+      it "triggers a matching event on Spree::Bus" do
+        run = false
+        subscription = Spree::Bus.subscribe(:"stripe.charge.succeeded") { run = true }
+
+        post "/solidus_stripe/webhooks", params: payload, headers: { signature_header_key => signature_header }
+
+        expect(run).to be(true)
+      ensure
+        Spree::Bus.unsubscribe(subscription)
+      end
+
+      it "binds the event to the subscriber" do
+        event_type = nil
+        subscription = Spree::Bus.subscribe(:"stripe.charge.succeeded") { |event| event_type = event.type }
+
+        post "/solidus_stripe/webhooks", params: payload, headers: { signature_header_key => signature_header }
+
+        expect(event_type).to eq("charge.succeeded")
+      ensure
+        Spree::Bus.unsubscribe(subscription)
+      end
+
+      it "returns a 200 status code" do
+        post "/solidus_stripe/webhooks", params: payload, headers: { signature_header_key => signature_header }
+
+        expect(response).to have_http_status(:ok)
+      end
+    end
+
+    context "when the signature is invalid" do
+      let(:payload) { JSON.generate(SolidusStripe::WebhookFixtures.charge_succeeded) }
+
+      it "returns a 400 status code" do
+        post "/solidus_stripe/webhooks", params: payload, headers: { signature_header_key => "t=1,v1=1" }
+
+        expect(response).to have_http_status(:bad_request)
+      end
+    end
+
+    context "when the payload is malformed" do
+      let(:payload) { "invalid" }
+
+      it "returns a 400 status code" do
+        post "/solidus_stripe/webhooks", params: payload, headers: { signature_header_key => signature_header }
+
+        expect(response).to have_http_status(:bad_request)
+      end
+    end
+  end
+  # rubocop:enable RSpec/MultipleMemoizedHelpers
+end