gocardless_pro 2.10.0 → 2.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 06d8895916dd0f220182f39eb35a9c286f50288c84391984715f2362b142319d
-  data.tar.gz: d2839e1c60c82d2907980843abb9c8e1e6a911d7a157752be15cf773b8333b4d
+  metadata.gz: e050e363d51abaf3c39a5f492efa1512145e38fd83b6ca89271c5a36912d58fb
+  data.tar.gz: 5570e9de8ac349af06b99a282246e69ff4df075826414f5bf9f2df06b65a52f2
 SHA512:
-  metadata.gz: 4cb9c53de215e5ad3c01d83f0568e3b6fa58bd5fc50daa43de0115977cf49e0d74f9e47836d99d1c5c0b9eb51663b778c4de572c7a8190cb97650b1d6cfbfa62
-  data.tar.gz: e247fb19810b43ca4131471833e700734c77231f0ebb8109da023229846c63cb1a12df04d232d2430ad69ec46fc9ce6e51ed4dc7a09d9d9066467125c72a8408
+  metadata.gz: 7187e0274d9cf84dec3562521da846c90fddd75316eecc4fbb69b4b62a124a21096fa1fc929ba39ac42bbe83e8e1aa8918b78dfa31ee69dacb7f4fc3812d416a
+  data.tar.gz: f72fb680bd59ac97db9da8341e46d87bc71be4b65a802d51f5eecb443d075d98e64327c1a2602497c4848074e7997636864523643d6b965ff33fd00bb7b60091

data/README.md

@@ -173,6 +173,60 @@ If the client is unable to connect to GoCardless, an appropriate exception will
 
 If an error occurs which is likely to be resolved with a retry (e.g. a timeout or connection error), and the request being made is idempotent, the library will automatically retry the request twice (i.e. it will make up to 3 attempts) before giving up and raising an exception.
 
+### Handling webhooks
+
+GoCardless supports webhooks, allowing you to receive real-time notifications when things happen in your account, so you can take automatic actions in response, for example:
+
+* When a customer cancels their mandate with the bank, suspend their club membership
+* When a payment fails due to lack of funds, mark their invoice as unpaid
+* When a customer’s subscription generates a new payment, log it in their “past payments” list
+
+The client allows you to validate that a webhook you receive is genuinely from GoCardless, and to parse it into `GoCardlessPro::Resources::Event` objects which are easy to work with:
+
+```ruby
+class WebhooksController < ApplicationController
+  include ActionController::Live
+
+  protect_from_forgery except: :create
+
+  def create
+    # When you create a webhook endpoint, you can specify a secret. When GoCardless sends
+    # you a webhook, it'll sign the body using that secret. Since only you and GoCardless
+    # know the secret, you can check the signature and ensure that the webhook is truly
+    # from GoCardless.
+    #
+    # We recommend storing your webhook endpoint secret in an environment variable
+    # for security, but you could include it as a string directly in your code
+    webhook_endpoint_secret = ENV['GOCARDLESS_WEBHOOK_ENDPOINT_SECRET']
+
+    begin
+      # This example is for Rails. In a Rack app (e.g. Sinatra), access the POST body with
+      # `request.body.tap(&:rewind).read` and the Webhook-Signature header with
+      # `request.env['HTTP_WEBHOOK_SIGNATURE']`.
+      events = GoCardlessPro::Webhook.parse(
+        request_body: request.raw_post,
+        signature_header: request.headers['Webhook-Signature'],
+        webhook_endpoint_secret: webhook_endpoint_secret
+      )
+
+      events.each do |event|
+        # You can access each event in the webhook.
+        puts event.id
+      end
+
+      render status: 200, nothing: true
+    rescue GoCardlessPro::Webhook::InvalidSignatureError
+      # The webhook doesn't appear to be genuinely from GoCardless, as the signature
+      # included in the `Webhook-Signature` header doesn't match one computed with your
+      # webhook endpoint secret and the body
+      render status: 498, nothing: true
+    end
+  end
+end
+```
+
+For more details on working with webhooks, see our ["Getting started" guide](https://developer.gocardless.com/getting-started/api/introduction/?lang=ruby).
+
 ### Using the OAuth API
 
 The API includes [OAuth](https://developer.gocardless.com/pro/2015-07-06/#guides-oauth) functionality, which allows you to work with other users' GoCardless accounts. Once a user approves you, you can use the GoCardless API on their behalf and receive their webhooks.

data/lib/gocardless_pro.rb

@@ -36,6 +36,7 @@ require_relative 'gocardless_pro/paginator'
 require_relative 'gocardless_pro/request'
 require_relative 'gocardless_pro/response'
 require_relative 'gocardless_pro/api_response'
+require_relative 'gocardless_pro/webhook'
 
 require_relative 'gocardless_pro/resources/bank_details_lookup'
 require_relative 'gocardless_pro/services/bank_details_lookups_service'

data/lib/gocardless_pro/client.rb

@@ -133,7 +133,7 @@ module GoCardlessPro
           'User-Agent' => user_agent.to_s,
           'Content-Type' => 'application/json',
           'GoCardless-Client-Library' => 'gocardless-pro-ruby',
-          'GoCardless-Client-Version' => '2.10.0',
+          'GoCardless-Client-Version' => '2.11.0',
         },
       }
     end

data/lib/gocardless_pro/resources/creditor_bank_account.rb

@@ -21,6 +21,10 @@ module GoCardlessPro
     # account. You may wish to handle this by updating the existing record
     # instead, the ID of which will be provided as
     # `links[creditor_bank_account]` in the error response.
+    #
+    # <p class="restricted-notice"><strong>Restricted</strong>: This API is not
+    # available for
+    # partner integrations.</p>
     class CreditorBankAccount
       attr_reader :account_holder_name
       attr_reader :account_number_ending

data/lib/gocardless_pro/version.rb

@@ -4,5 +4,5 @@ end
 
 module GoCardlessPro
   # Current version of the GC gem
-  VERSION = '2.10.0'.freeze
+  VERSION = '2.11.0'.freeze
 end

data/lib/gocardless_pro/webhook.rb

@@ -0,0 +1,97 @@
+require 'openssl'
+
+module GoCardlessPro
+  class Webhook
+    class InvalidSignatureError < StandardError; end
+
+    class << self
+      # Validates that a webhook was genuinely sent by GoCardless using
+      # `.signature_valid?`, and then parses it into an array of
+      # `GoCardlessPro::Resources::Event` objects representing each event
+      # included in the webhook
+      #
+      # @option options [String] :request_body the request body
+      # @option options [String] :signature_header the signature included in the request,
+      #   found in the `Webhook-Signature` header
+      # @option options [String] :webhook_endpoint_secret the webhook endpoint secret for
+      #   your webhook endpoint, as configured in your GoCardless Dashboard
+      # @return [Array<GoCardlessPro::Resources::Event>] the events included
+      #   in the webhook
+      # @raise [InvalidSignatureError] if the signature header specified does not match
+      #   the signature computed using the request body and webhook endpoint secret
+      # @raise [ArgumentError] if a required keyword argument is not provided or is not
+      #   of the required type
+      def parse(options = {})
+        validate_options!(options)
+
+        unless signature_valid?(request_body: options[:request_body],
+                                signature_header: options[:signature_header],
+                                webhook_endpoint_secret: options[:webhook_endpoint_secret])
+          raise InvalidSignatureError, "This webhook doesn't appear to be a genuine " \
+                                        'webhook from GoCardless, because the signature ' \
+                                        "header doesn't match the signature computed" \
+                                        ' with your webhook endpoint secret.'
+        end
+
+        events = JSON.parse(options[:request_body])['events']
+
+        events.map { |event| Resources::Event.new(event) }
+      end
+
+      # Validates that a webhook was genuinely sent by GoCardless by computing its
+      # signature using the body and your webhook endpoint secret, and comparing that with
+      # the signature included in the `Webhook-Signature` header
+      #
+      # @option options [String] :request_body the request body
+      # @option options [String] :signature_header the signature included in the request,
+      #   found in the `Webhook-Signature` header
+      # @option options [String] :webhook_endpoint_secret the webhook endpoint secret for
+      #   your webhook endpoint, as configured in your GoCardless Dashboard
+      # @return [Boolean] whether the webhook's signature is valid
+      # @raise [ArgumentError] if a required keyword argument is not provided or is not
+      #   of the required type
+      def signature_valid?(options = {})
+        validate_options!(options)
+
+        computed_signature = OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new('sha256'),
+                                                     options[:webhook_endpoint_secret],
+                                                     options[:request_body])
+
+        secure_compare(options[:signature_header], computed_signature)
+      end
+
+      private
+
+      # Performs a "constant time" comparison of two strings, safe against timing attacks
+      #
+      # Vendored from Rack's `Rack::Utils.secure_compare`
+      # (https://github.com/rack/rack/blob/eb040cf1bbb1b2dacd496ab0aa549de8408d8a27/lib/rack/utils.rb#L368-L382).
+      # Licensed under The MIT License (MIT). Copyright (C) 2007-2018 Christian
+      # Neukirchen.
+      def secure_compare(a, b)
+        return false unless a.bytesize == b.bytesize
+        l = a.unpack('C*')
+
+        r = 0
+        i = -1
+        b.each_byte { |v| r |= v ^ l[i += 1] }
+        r == 0
+      end
+
+      def validate_options!(options)
+        unless options[:request_body].is_a?(String)
+          raise ArgumentError, 'request_body must be provided and must be a string'
+        end
+
+        unless options[:signature_header].is_a?(String)
+          raise ArgumentError, 'signature_header must be provided and must be a string'
+        end
+
+        unless options[:webhook_endpoint_secret].is_a?(String)
+          raise ArgumentError, 'webhook_endpoint_secret must be provided and must be a ' \
+                               'string'
+        end
+      end
+    end
+  end
+end

data/spec/webhook_spec.rb

@@ -0,0 +1,122 @@
+require 'spec_helper'
+require 'pathname'
+
+describe GoCardlessPro::Webhook do
+  let(:options) do
+    {
+      request_body: request_body,
+      signature_header: signature_header,
+      webhook_endpoint_secret: webhook_endpoint_secret,
+    }
+  end
+
+  let(:request_body) do
+    '{"events":[{"id":"EV00BD05S5VM2T","created_at":"2018-07-05T09:13:51.404Z","resou' \
+    'rce_type":"subscriptions","action":"created","links":{"subscription":"SB0003JJQ2' \
+    'MR06"},"details":{"origin":"api","cause":"subscription_created","description":"S' \
+    'ubscription created via the API."},"metadata":{}},{"id":"EV00BD05TB8K63","create' \
+    'd_at":"2018-07-05T09:13:56.893Z","resource_type":"mandates","action":"created","' \
+    'links":{"mandate":"MD000AMA19XGEC"},"details":{"origin":"api","cause":"mandate_c' \
+    'reated","description":"Mandate created via the API."},"metadata":{}}]}'
+  end
+
+  let(:signature_header) do
+    '2693754819d3e32d7e8fcb13c729631f316c6de8dc1cf634d6527f1c07276e7e'
+  end
+
+  let(:webhook_endpoint_secret) { 'ED7D658C-D8EB-4941-948B-3973214F2D49' }
+
+  describe '.parse' do
+    context 'when the signature in the header matches the computed signature' do
+      it 'returns an array of `GoCardlessPro::Resources::Event`s' do
+        events = described_class.parse(options)
+
+        expect(events.length).to eq(2)
+
+        expect(events.first.id).to eq('EV00BD05S5VM2T')
+        expect(events.first.created_at).to eq('2018-07-05T09:13:51.404Z')
+        expect(events.first.resource_type).to eq('subscriptions')
+        expect(events.first.action).to eq('created')
+        expect(events.first.links.subscription).to eq('SB0003JJQ2MR06')
+        expect(events.first.details['origin']).to eq('api')
+        expect(events.first.details['cause']).to eq('subscription_created')
+        expect(events.first.details['description']).
+          to eq('Subscription created via the API.')
+        expect(events.first.metadata).to eq({})
+
+        expect(events.last.id).to eq('EV00BD05TB8K63')
+        expect(events.last.created_at).to eq('2018-07-05T09:13:56.893Z')
+        expect(events.last.resource_type).to eq('mandates')
+        expect(events.last.action).to eq('created')
+        expect(events.last.links.mandate).to eq('MD000AMA19XGEC')
+        expect(events.last.details['origin']).to eq('api')
+        expect(events.last.details['cause']).to eq('mandate_created')
+        expect(events.last.details['description']).
+          to eq('Mandate created via the API.')
+        expect(events.last.metadata).to eq({})
+      end
+    end
+
+    context "when the signature in the header doesn't match the computed signature" do
+      let(:webhook_endpoint_secret) { 'foo' }
+
+      it 'raises an InvalidSignatureError' do
+        expect { described_class.parse(options) }.
+          to raise_error(described_class::InvalidSignatureError,
+                         /doesn't appear to be a genuine webhook from GoCardless/)
+      end
+    end
+
+    context 'with a required argument missing' do
+      before { options.delete(:request_body) }
+
+      it 'raises an ArgumentError' do
+        expect { described_class.signature_valid?(options) }.
+          to raise_error(ArgumentError,
+                         'request_body must be provided and must be a string')
+      end
+    end
+
+    context 'with an argument of the wrong type' do
+      let(:request_body) { StringIO.new }
+
+      it 'raises an ArgumentError' do
+        expect { described_class.signature_valid?(options) }.
+          to raise_error(ArgumentError,
+                         'request_body must be provided and must be a string')
+      end
+    end
+  end
+
+  describe '.signature_valid?' do
+    context 'when the signature in the header matches the computed signature' do
+      specify { expect(described_class.signature_valid?(options)).to be(true) }
+    end
+
+    context "when the signature in the header doesn't match the computed signature" do
+      let(:webhook_endpoint_secret) { 'foo' }
+
+      specify { expect(described_class.signature_valid?(options)).to be(false) }
+    end
+
+    context 'with a required argument missing' do
+      before { options.delete(:request_body) }
+
+      it 'raises an ArgumentError' do
+        expect { described_class.signature_valid?(options) }.
+          to raise_error(ArgumentError,
+                         'request_body must be provided and must be a string')
+      end
+    end
+
+    context 'with an argument of the wrong type' do
+      let(:request_body) { StringIO.new }
+
+      it 'raises an ArgumentError' do
+        expect { described_class.signature_valid?(options) }.
+          to raise_error(ArgumentError,
+                         'request_body must be provided and must be a string')
+      end
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: gocardless_pro
 version: !ruby/object:Gem::Version
-  version: 2.10.0
+  version: 2.11.0
 platform: ruby
 authors:
 - GoCardless
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-06-06 00:00:00.000000000 Z
+date: 2018-07-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -151,6 +151,7 @@ files:
 - lib/gocardless_pro/services/refunds_service.rb
 - lib/gocardless_pro/services/subscriptions_service.rb
 - lib/gocardless_pro/version.rb
+- lib/gocardless_pro/webhook.rb
 - spec/api_response_spec.rb
 - spec/api_service_spec.rb
 - spec/client_spec.rb
@@ -190,6 +191,7 @@ files:
 - spec/services/refunds_service_spec.rb
 - spec/services/subscriptions_service_spec.rb
 - spec/spec_helper.rb
+- spec/webhook_spec.rb
 homepage: https://github.com/gocardless/gocardless-pro-ruby
 licenses:
 - MIT
@@ -254,3 +256,4 @@ test_files:
 - spec/services/refunds_service_spec.rb
 - spec/services/subscriptions_service_spec.rb
 - spec/spec_helper.rb
+- spec/webhook_spec.rb