paypal-rest-api 0.0.4 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f8570bf045fe3986e03358401550d77f16dc5667c9da1c3e233fd07b95231c3e
-  data.tar.gz: e41098ed451a8997eff6bc0720f0c957c68fd843f8d2bee7b44cbd794c7913f0
+  metadata.gz: 161078b6b9ff7513fe6634bc4e37c181374858dec0cac4261d5cc662d115787c
+  data.tar.gz: 60346804bbd8a930f695a922a6ce07adaefca26e25f7777e70de0d9f5d87a01a
 SHA512:
-  metadata.gz: 193437cd7bf07228015eaead34a84952c14e02e3eca154df7df6df1eabcd28a26c4cc99a92ee16df03810b7c1c6824a4605fadf8e3008cf98053d1fa6cd1c883
-  data.tar.gz: dd2098b7c52ba4b8d1fc41a2152d7848168b7c831a2705acdfcacb5aab9ea3c80194401a2d883f7853fd8614cd4079c49788da0c6e7cfd35c614a7d41ff27f8c
+  metadata.gz: e340f1e223aa903aed6fde693f4a16dc9cdf0ef3d474a633e171b7890eb016d8c42ef593117385419bd07c366bb257bbc0adbbcab8b193cb150523cd3dcaee46
+  data.tar.gz: 74f017ec1aabca6d9a55599bacc32ee7d7d2c425ec109ec076d2f8072819d95047a07d763ed7b5ba0bd4b96a3b91a3aa3b2404d1a0602c2704028661b544a18b

data/README.md

@@ -8,11 +8,14 @@ bundle add paypal-rest-api
 
 ## Features
 
+- Supported Ruby 2.6 - current Head
 - No dependencies;
 - Automatic authorization & reauthorization;
 - Auto-retries (configured);
 - Automatically added Paypal-Request-Id header for idempotent requests if not
   provided;
+- Webhooks Offline verification (needs to download certificate once)
+- Custom callbacks before/after request
 
 ## Usage
 
@@ -71,11 +74,11 @@ response = PaypalAPI.delete(path, query: query, body: body, headers: headers)
 
 ### Parsing response
 
-`response.body` is a main method that returns parsed JSON respoonse as a HASH.
+`response.body` is a main method that returns parsed JSON respoonse as a Hash.
 
 There are also many others helpful methods:
 
-```
+```ruby
 response.body # Parsed JSON. JSON is parsed lazyly, keys are symbolized.
 response[:foo] # Gets :foo attribute from parsed body
 response.fetch(:foo) # Fetches :foo attribute from parsed body
@@ -83,7 +86,7 @@ response.http_response # original Net::HTTP::Response
 response.http_body # original response string
 response.http_status # Integer http status
 response.http_headers # Hash with response headers (keys are strings)
-response.requested_at # Time when request was sent
+response.request # Request that generates this response
 ```
 
 ## Configuration options
@@ -136,6 +139,108 @@ client = PaypalAPI::Client.new(
 )
 ```
 
+## Webhoooks verification
+
+Webhooks can be verified [offline](https://developer.paypal.com/api/rest/webhooks/rest/#link-selfverificationmethod)
+or [online](https://developer.paypal.com/api/rest/webhooks/rest/#link-postbackmethod).
+Method `PaypalAPI.verify_webhook(webhook_id:, headers:, raw_body:)`
+verifies webhook. It to verify webhook OFFLINE and it fallbacks
+to ONLINE if offline verification returns false to be sure you don't miss a
+valid webhook.
+
+When some required header is missing it will raise
+`PaypalAPI::WebhooksVerifier::MissingHeader` error.
+
+Example of Rails controller with webhook verification:
+
+```ruby
+class Webhooks::PaypalController < ApplicationController
+  def create
+    # PayPal registered webhook ID for current URL
+    webhook_id = ENV['PAYPAL_WEBHOOK_ID']
+    headers = request.headers # must be a Hash
+    raw_body = request.raw_post # must be a raw String body
+
+    webhook_is_valid = PaypalAPI.verify_webhook(
+      webhook_id: webhook_id,
+      headers: headers,
+      raw_body: raw_body
+    )
+
+    if webhook_is_valid
+      handle_valid_webhook_event(body)
+    else
+      handle_invalid_webhook_event(webhook_id, headers, body)
+    end
+
+    head :no_content
+  end
+end
+```
+
+## Callbacks
+
+Callbacks list:
+
+- `:before` - Runs before request
+- `:after_success` - Runs after getting successful response
+- `:after_fail` - Runs after getting failed response (non-2xx) status code
+- `:after_network_error` - Runs after getting network error
+
+Callbacks are registered on `client` object.
+
+Each callback receive `request` and `context` variables.
+`context` can be modified manually to save state between callbacks.
+
+`:after_success` and `:after_fail` callbacks have additional `response` argument
+
+`:after_network_error` callback has additional `error` argument
+
+```ruby
+PaypalAPI.client.add_callback(:before) do |request, context|
+  context[:request_id] = SecureRandom.hex(3)
+  context[:starts_at] = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+end
+
+PaypalAPI.client.add_callback(:after) do |request, context, response|
+  ends_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+  duration = ends_at - context[:starts_at]
+
+  SomeLogger.debug(
+    'PaypalAPI success request',
+    method: request.method,
+    uri: request.uri.to_s,
+    duration: duration
+  )
+end
+
+PaypalAPI.client.add_callback(:after_fail) do |request, context, response|
+  SomeLogger.error(
+    'PaypalAPI request failed',
+    method: request.method,
+    uri: request.uri.to_s,
+    response_status: response.http_status,
+    response_body: response.http_body,
+    will_retry: context[:will_retry],
+    retry_number: context[:retry_number],
+    retry_count: context[:retry_count]
+  )
+end
+
+PaypalAPI.client.add_callback(:after_network_error) do |request, context, error|
+  SomeLogger.error(
+    'PaypalAPI network connection error'
+    method: request.method,
+    uri: request.uri.to_s,
+    error: error.message,
+    paypal_request_id: request.headers['paypal-request-id'],
+    will_retry: context[:will_retry],
+    retry_number: context[:retry_number],
+    retry_count: context[:retry_count]
+  )
+end
+```
+
 ## Errors
 
 All APIs can raise error in case of network error or non-2xx response status code.

data/VERSION

@@ -1 +1 @@
-0.0.4
+0.1.0

data/lib/paypal-api/client.rb

@@ -5,7 +5,7 @@ module PaypalAPI
   # PaypalAPI Client
   #
   class Client
-    attr_reader :config
+    attr_reader :config, :callbacks
 
     # Initializes Client
     # @api public
@@ -18,18 +18,49 @@ module PaypalAPI
     #
     # @return [Client] Initialized client
     #
-    def initialize(client_id:, client_secret:, live: nil, http_opts: nil, retries: nil)
+    def initialize(client_id:, client_secret:, live: nil, http_opts: nil, retries: nil, cache: nil)
       @config = PaypalAPI::Config.new(
         client_id: client_id,
         client_secret: client_secret,
         live: live,
         http_opts: http_opts,
-        retries: retries
+        retries: retries,
+        cache: cache
       )
 
+      @callbacks = {
+        before: [],
+        after_success: [],
+        after_fail: [],
+        after_network_error: []
+      }.freeze
+
       @access_token = nil
     end
 
+    # Registers callback
+    #
+    # @param callback_name [Symbol] Callback name.
+    #   Allowed values: :before, :after_success, :after_faile, :after_network_error
+    #
+    # @param block [Proc] Block that must be call
+    #   For `:before` callback proc should accept 2 params -
+    #    request [Request], context [Hash]
+    #
+    #   For `:after_success` callback proc should accept 3 params -
+    #     request [Request], context [Hash], response [Response]
+    #
+    #   For `:after_fail` callback proc should accept 3 params -
+    #     request [Request], context [Hash], error [StandardError]
+    #
+    #   For `:after_network_error` callback proc should accept 3 params -
+    #     request [Request], context [Hash], response [Response]
+    #
+    # @return [void]
+    def add_callback(callback_name, &block)
+      callbacks.fetch(callback_name) << block
+    end
+
     #
     # Checks cached access token is expired and returns it or generates new one
     #
@@ -45,16 +76,48 @@ module PaypalAPI
     # @return [AccessToken] new AccessToken object
     #
     def refresh_access_token
+      requested_at = Time.now
       response = authentication.generate_access_token
 
       @access_token = AccessToken.new(
-        requested_at: response.requested_at,
+        requested_at: requested_at,
         expires_in: response.fetch(:expires_in),
         access_token: response.fetch(:access_token),
         token_type: response.fetch(:token_type)
       )
     end
 
+    #
+    # Verifies Webhook
+    # It requires one-time request to download and cache certificate.
+    # If local verification returns false it tries to verify webhook online.
+    #
+    # @api public
+    # @example
+    #
+    #  class Webhooks::PaypalController < ApplicationController
+    #    def create
+    #      webhook_id = ENV['PAYPAL_WEBHOOK_ID'] # PayPal registered webhook ID for current URL
+    #      headers = request.headers # must be a Hash
+    #      body = request.raw_post # must be a raw String body
+    #
+    #      webhook_is_valid = PaypalAPI.verify_webhook(webhook_id: webhook_id, headers: headers, body: body)
+    #      webhook_is_valid ? handle_webhook_event(body) : log_error(webhook_id, headers, body)
+    #
+    #      head :no_content
+    #    end
+    #  end
+    #
+    # @param webhook_id [String] webhook_id provided by PayPal when webhook was registered
+    # @param headers [Hash,#[]] webhook request headers
+    # @param raw_body [String] webhook request raw body string
+    #
+    # @return [Boolean] webhook event is valid
+    #
+    def verify_webhook(webhook_id:, headers:, raw_body:)
+      WebhookVerifier.new(self).call(webhook_id: webhook_id, headers: headers, raw_body: raw_body)
+    end
+
     # @!macro [new] request
     # @param path [String] Request path
     # @param query [Hash, nil] Request query parameters
@@ -217,7 +280,7 @@ module PaypalAPI
 
     def execute_request(http_method, path, query: nil, body: nil, headers: nil)
       request = Request.new(self, http_method, path, query: query, body: body, headers: headers)
-      RequestExecutor.call(request)
+      RequestExecutor.new(self, request).call
     end
   end
 end

data/lib/paypal-api/config.rb

@@ -18,7 +18,7 @@ module PaypalAPI
       retries: {enabled: true, count: 3, sleep: [0.25, 0.75, 1.5].freeze}.freeze
     }.freeze
 
-    attr_reader :client_id, :client_secret, :live, :http_opts, :retries
+    attr_reader :client_id, :client_secret, :live, :http_opts, :retries, :certs_cache
 
     # Initializes Config
     #
@@ -27,15 +27,19 @@ module PaypalAPI
     # @param live [Boolean] PayPal live/sandbox mode
     # @param http_opts [Hash] Net::Http opts for all requests
     # @param retries [Hash] Retries configuration
+    # @param cache [#read, nil] Application cache to store certificates to validate webhook events locally.
+    #   Must respond to #read(key) and #write(key, expires_in: Integer)
     #
     # @return [Client] Initialized config object
     #
-    def initialize(client_id:, client_secret:, live: nil, http_opts: nil, retries: nil)
+    def initialize(client_id:, client_secret:, live: nil, http_opts: nil, retries: nil, cache: nil)
       @client_id = client_id
       @client_secret = client_secret
       @live = with_default(:live, live)
       @http_opts = with_default(:http_opts, http_opts)
       @retries = with_default(:retries, retries)
+      @certs_cache = WebhookVerifier::CertsCache.new(cache)
+
       freeze
     end
 

data/lib/paypal-api/request.rb

@@ -19,8 +19,8 @@ module PaypalAPI
     # @return [Net::HTTPRequest] Generated Net::HTTPRequest
     attr_reader :http_request
 
-    # @return [Time, nil] Time when request was sent
-    attr_accessor :requested_at
+    # @return [Hash, nil, Object] Custom context that can be set/changed in callbacks
+    attr_accessor :context
 
     # rubocop:disable Metrics/ParameterLists
 
@@ -40,48 +40,80 @@ module PaypalAPI
     def initialize(client, request_type, path, body: nil, query: nil, headers: nil)
       @client = client
       @http_request = build_http_request(request_type, path, body: body, query: query, headers: headers)
-      @requested_at = nil
+      @context = nil
     end
     # rubocop:enable Metrics/ParameterLists
 
+    # @return [String] HTTP request method name
+    def method
+      http_request.method
+    end
+
+    # @return [String] HTTP request method name
+    def path
+      http_request.path
+    end
+
+    # @return [URI] HTTP request URI
+    def uri
+      http_request.uri
+    end
+
+    # @return [String] HTTP request body
+    def body
+      http_request.body
+    end
+
+    # @return [Hash] HTTP request headers
+    def headers
+      http_request.each_header.to_h
+    end
+
     private
 
     def build_http_request(request_type, path, body:, query:, headers:)
-      uri = request_uri(path, query)
-      http_request = request_type.new(uri)
+      uri = build_http_uri(path, query)
+      http_request = request_type.new(uri, "accept-encoding" => nil)
 
-      add_headers(http_request, headers || {})
-      add_body(http_request, body)
+      build_http_headers(http_request, body, headers || {})
+      build_http_body(http_request, body)
 
       http_request
     end
 
-    def add_headers(http_request, headers)
-      headers.each { |key, value| http_request[key] = value }
+    def build_http_headers(http_request, body, headers)
+      headers = normalize_headers(headers)
+
+      unless headers.key?("authorization")
+        http_request["authorization"] = client.access_token.authorization_string
+      end
+
+      unless headers.key?("content-type")
+        http_request["content-type"] = "application/json" if body
+      end
 
-      http_request["content-type"] ||= "application/json"
-      http_request["authorization"] ||= client.access_token.authorization_string
-      http_request["paypal-request-id"] ||= SecureRandom.uuid if idempotent?(http_request)
+      unless headers.key?("paypal-request-id")
+        http_request["paypal-request-id"] = SecureRandom.uuid unless http_request.is_a?(Net::HTTP::Get)
+      end
+
+      headers.each { |key, value| http_request[key] = value }
     end
 
-    def add_body(http_request, body)
+    def build_http_body(http_request, body)
       return unless body
 
-      json?(http_request) ? http_request.body = JSON.dump(body) : http_request.set_form_data(body)
+      is_json = http_request["content-type"].include?("json")
+      is_json ? http_request.body = JSON.dump(body) : http_request.set_form_data(body)
     end
 
-    def request_uri(path, query)
+    def build_http_uri(path, query)
       uri = URI.join(client.config.url, path)
       uri.query = URI.encode_www_form(query) if query && !query.empty?
       uri
     end
 
-    def idempotent?(http_request)
-      http_request.method != Net::HTTP::Get::METHOD
-    end
-
-    def json?(http_request)
-      http_request["content-type"].include?("json")
+    def normalize_headers(headers)
+      headers.empty? ? headers : headers.transform_keys { |key| key.to_s.downcase }
     end
   end
 end

data/lib/paypal-api/request_executor.rb

@@ -5,91 +5,106 @@ module PaypalAPI
   # Executes PaypalAPI::Request and returns PaypalAPI::Response or raises PaypalAPI::Error
   #
   class RequestExecutor
-    # List of Net::HTTP responses that must be retried
-    RETRYABLE_RESPONSES = [
-      Net::HTTPServerError,    # 5xx
-      Net::HTTPConflict,       # 409
-      Net::HTTPTooManyRequests # 429
-    ].freeze
-
-    class << self
-      #
-      # Executes prepared Request, handles retries and preparation of errors
-      #
-      # @param [Request] request
-      #
-      # @return [Response] Response
-      #
-      def call(request)
-        http_response = execute(request)
-        response = Response.new(http_response, requested_at: request.requested_at)
-        raise FailedRequestErrorBuilder.call(request: request, response: response) unless http_response.is_a?(Net::HTTPSuccess)
+    attr_reader :client, :request, :http_opts, :context, :retries, :callbacks, :callbacks_context
+
+    def initialize(client, request)
+      @client = client
+      @request = request
+      @http_opts = {use_ssl: request.uri.is_a?(URI::HTTPS), **client.config.http_opts}
+      @retries = client.config.retries
+      @callbacks = client.callbacks
+      @callbacks_context = {retries_count: retries[:count]}
+    end
 
-        response
-      end
+    #
+    # Executes prepared Request, handles retries and preparation of errors
+    #
+    # @return [Response] Response
+    #
+    def call
+      response = execute_request
+      raise FailedRequestErrorBuilder.call(request: request, response: response) if response.failed?
+
+      response
+    end
+
+    private
 
-      private
+    def execute_request(retry_number: 0)
+      callbacks_context[:retry_number] = retry_number
 
-      def execute(request, retry_number: 0)
-        http_response = execute_http_request(request)
-      rescue *NetworkErrorBuilder::ERRORS => error
-        retry_on_network_error(request, error, retry_number)
+      run_callbacks(:before)
+      response = execute_net_http_request
+    rescue *NetworkErrorBuilder::ERRORS => error
+      will_retry = !retries_limit_reached?(retry_number)
+      callbacks_context[:will_retry] = will_retry
+      run_callbacks(:after_network_error, error)
+      raise NetworkErrorBuilder.call(request: request, error: error) unless will_retry
+
+      retry_request(retry_number)
+    else
+      if response.success?
+        callbacks_context.delete(:will_retry)
+        run_callbacks(:after_success, response)
+        response
       else
-        retryable?(request, http_response, retry_number) ? retry_request(request, retry_number) : http_response
+        will_retry = retryable?(response, retry_number)
+        callbacks_context[:will_retry] = will_retry
+        run_callbacks(:after_fail, response)
+        will_retry ? retry_request(retry_number) : response
       end
+    end
 
-      def execute_http_request(request)
-        http_request = request.http_request
-        http_opts = request.client.config.http_opts
-        uri = http_request.uri
-        request.requested_at = Time.now
+    def execute_net_http_request
+      uri = request.uri
 
-        Net::HTTP.start(uri.hostname, uri.port, use_ssl: true, **http_opts) do |http|
+      http_response =
+        Net::HTTP.start(uri.hostname, uri.port, **http_opts) do |http|
           http.max_retries = 0 # we have custom retries logic
-          http.request(http_request)
+          http.request(request.http_request)
         end
-      end
 
-      def retry_on_network_error(request, error, retry_number)
-        raise NetworkErrorBuilder.call(request: request, error: error) if retries_limit_reached?(request, retry_number)
+      Response.new(http_response, request: request)
+    end
 
-        retry_request(request, retry_number)
-      end
+    def retry_request(current_retry_number)
+      sleep_time = retry_sleep_seconds(current_retry_number)
+      sleep(sleep_time) if sleep_time.positive?
+      execute_request(retry_number: current_retry_number + 1)
+    end
 
-      def retry_request(request, current_retry_number)
-        sleep(retry_sleep_seconds(request, current_retry_number))
-        execute(request, retry_number: current_retry_number + 1)
-      end
+    def retries_limit_reached?(retry_number)
+      retry_number >= retries[:count]
+    end
 
-      def retries_limit_reached?(request, retry_number)
-        retry_number >= request.client.config.retries[:count]
-      end
+    def retry_sleep_seconds(current_retry_number)
+      seconds_per_retry = retries[:sleep]
+      seconds_per_retry[current_retry_number] || seconds_per_retry.last || 1
+    end
 
-      def retry_sleep_seconds(request, current_retry_number)
-        seconds_per_retry = request.client.config.retries[:sleep]
-        seconds_per_retry[current_retry_number] || seconds_per_retry.last || 1
-      end
+    def retryable?(response, retry_number)
+      response.failed? &&
+        !retries_limit_reached?(retry_number) &&
+        retryable_request?(response)
+    end
 
-      def retryable?(request, http_response, retry_number)
-        !http_response.is_a?(Net::HTTPSuccess) &&
-          !retries_limit_reached?(request, retry_number) &&
-          retryable_request?(request, http_response)
-      end
+    def retryable_request?(response)
+      return true if response.retryable?
 
-      def retryable_request?(request, http_response)
-        return true if RETRYABLE_RESPONSES.any? { |retryable_class| http_response.is_a?(retryable_class) }
+      retry_unauthorized?(response)
+    end
 
-        retry_unauthorized?(request, http_response)
-      end
+    def retry_unauthorized?(response)
+      return false unless response.unauthorized? # 401
+      return false if request.path == Authentication::PATH # it's already an Authentication request
 
-      def retry_unauthorized?(request, http_response)
-        return false unless http_response.is_a?(Net::HTTPUnauthorized) # 401
-        return false if http_response.uri.path == Authentication::PATH # it's already an Authentication request
+      # set new access-token
+      request.http_request["authorization"] = client.refresh_access_token.authorization_string
+      true
+    end
 
-        # set new access-token
-        request.http_request["authorization"] = request.client.refresh_access_token.authorization_string
-        true
-      end
+    def run_callbacks(callback_name, resp = nil)
+      callbacks[callback_name].each { |callback| callback.call(request, context, resp) }
     end
   end
 end

data/lib/paypal-api/response.rb

@@ -7,22 +7,29 @@ module PaypalAPI
   # PaypalAPI::Response object
   #
   class Response
+    # List of Net::HTTP responses that can be retried
+    RETRYABLE_RESPONSES = [
+      Net::HTTPServerError,    # 5xx
+      Net::HTTPConflict,       # 409
+      Net::HTTPTooManyRequests # 429
+    ].freeze
+
     # @return [Net::HTTP::Response] Original Net::HTTP::Response object
     attr_reader :http_response
 
-    # @return [Time] Time when request was sent
-    attr_reader :requested_at
+    # @return [Request] Request object
+    attr_reader :request
 
     #
     # Initializes Response object
     #
     # @param http_response [Net::HTTP::Response] original response
-    # @param requested_at [Time] Time when original response was requested
+    # @param request [Request] Request that generates this response
     #
     # @return [Response] Initialized Response object
     #
-    def initialize(http_response, requested_at:)
-      @requested_at = requested_at
+    def initialize(http_response, request:)
+      @request = request
       @http_response = http_response
       @http_status = nil
       @http_headers = nil
@@ -64,6 +71,36 @@ module PaypalAPI
       data.fetch(key.to_sym)
     end
 
+    # Checks http status code is 2xx
+    #
+    # @return [Boolean] Returns true if response has success status code (2xx)
+    def success?
+      http_response.is_a?(Net::HTTPSuccess)
+    end
+
+    # Checks http status code is not 2xx
+    #
+    # @return [Boolean] Returns true if response has not success status code
+    def failed?
+      !success?
+    end
+
+    # Checks if response status code is retriable (5xx, 409, 429)
+    # @api private
+    #
+    # @return [Boolean] Returns true if status code is retriable (5xx, 409, 429)
+    def retryable?
+      failed? && RETRYABLE_RESPONSES.any? { |retryable_class| http_response.is_a?(retryable_class) }
+    end
+
+    # Checks if response status code is unauthorized (401)
+    # @api private
+    #
+    # @return [Boolean] Returns true if status code is retriable (5xx, 409, 429)
+    def unauthorized?
+      http_response.is_a?(Net::HTTPUnauthorized)
+    end
+
     #
     # Instance representation string. Default was overwritten to hide secrets
     #

data/lib/paypal-api/webhook_verifier/certs_cache.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module PaypalAPI
+  class WebhookVerifier
+    #
+    # Stores certifiactes in-memory.
+    #
+    # New values are added to this in-memory cache and application cache.
+    # When fetching value it firstly looks to the memory cache and then to the app cache.
+    #
+    # @api private
+    #
+    class CertsCache
+      # Current application cache
+      # @api private
+      attr_reader :app_cache
+
+      # Hash storage of certificate public keys
+      # @api private
+      attr_reader :storage
+
+      # Initializes certificates cache
+      #
+      # @param app_cache [#fetch, nil] Application cache that can store
+      #   certificates between redeploys
+      #
+      # @return [CertsCache]
+      def initialize(app_cache)
+        @app_cache = app_cache || NullCache
+        @storage = {}
+      end
+
+      # Fetches value from cache
+      #
+      # @param key [String] Cache key
+      # @param block [Proc] Proc to fetch certificate text
+      #
+      # @return [OpenSSL::PKey::PKey] Certificate Public Key
+      def fetch(key, &block)
+        openssl_pub_key = read(key)
+        return openssl_pub_key if openssl_pub_key
+
+        cert_string = app_cache.fetch(key, &block)
+        cert = OpenSSL::X509::Certificate.new(cert_string)
+
+        write(key, cert.public_key)
+      end
+
+      private
+
+      def write(key, value)
+        storage[key] = value
+      end
+
+      def read(key)
+        storage[key]
+      end
+    end
+
+    #
+    # Null-object cache class.
+    # Implements only #read and #write method.
+    #
+    # @api private
+    #
+    class NullCache
+      # Just calls provided block
+      # @param _key [String] Cache key
+      # @return [String] block result
+      def self.fetch(_key)
+        yield
+      end
+    end
+  end
+end

data/lib/paypal-api/webhook_verifier.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require "zlib"
+
+module PaypalAPI
+  #
+  # Webhook Verifier
+  # @api private
+  #
+  class WebhookVerifier
+    # Error that can happen when verifying webhook when some required headers are missing
+    class MissingHeader < StandardError
+    end
+
+    # @return [Client] current client
+    attr_reader :client
+
+    def initialize(client)
+      @client = client
+    end
+
+    # Verifies Webhook.
+    #
+    # It requires one-time request to download and cache certificate.
+    # If local verification returns false it tries to verify webhook online.
+    #
+    # @param webhook_id [String] Webhook ID provided by PayPal when registering webhook for your URL
+    # @param headers [Hash] webhook request headers
+    # @param raw_body [String] webhook request raw body string
+    #
+    # @return [Boolean]
+    def call(webhook_id:, headers:, raw_body:)
+      args = {
+        webhook_id: webhook_id,
+        raw_body: raw_body,
+        auth_algo: paypal_auth_algo(headers),
+        transmission_sig: paypal_transmission_sig(headers),
+        transmission_id: paypal_transmission_id(headers),
+        transmission_time: paypal_transmission_time(headers),
+        cert_url: paypal_cert_url(headers)
+      }
+
+      offline(**args) || online(**args)
+    end
+
+    private
+
+    def offline(webhook_id:, auth_algo:, transmission_sig:, transmission_id:, transmission_time:, cert_url:, raw_body:)
+      return false unless auth_algo.downcase.start_with?("sha256")
+
+      signature = paypal_signature(transmission_sig)
+      checked_data = "#{transmission_id}|#{transmission_time}|#{webhook_id}|#{Zlib.crc32(raw_body)}"
+      openssl_pub_key = download_and_cache_certificate(cert_url)
+
+      digest = OpenSSL::Digest.new("sha256", signature)
+      openssl_pub_key.verify(digest, signature, checked_data)
+    end
+
+    def online(webhook_id:, auth_algo:, transmission_sig:, transmission_id:, transmission_time:, cert_url:, raw_body:)
+      body = {
+        webhook_id: webhook_id,
+        auth_algo: auth_algo,
+        cert_url: cert_url,
+        transmission_id: transmission_id,
+        transmission_sig: transmission_sig,
+        transmission_time: transmission_time,
+        webhook_event: JSON.parse(raw_body)
+      }
+
+      response = client.webhooks.verify(body: body)
+      response[:verification_status] == "SUCCESS"
+    end
+
+    def paypal_signature(transmission_sig)
+      transmission_sig.unpack1("m") # decode base64
+    end
+
+    def paypal_transmission_sig(headers)
+      headers["paypal-transmission-sig"] || (raise MissingHeader, "No `paypal-transmission-sig` header")
+    end
+
+    def paypal_transmission_id(headers)
+      headers["paypal-transmission-id"] || (raise MissingHeader, "No `paypal-transmission-id` header")
+    end
+
+    def paypal_transmission_time(headers)
+      headers["paypal-transmission-time"] || (raise MissingHeader, "No `paypal-transmission-time` header")
+    end
+
+    def paypal_cert_url(headers)
+      headers["paypal-cert-url"] || (raise MissingHeader, "No `paypal-cert-url` header")
+    end
+
+    def paypal_auth_algo(headers)
+      headers["paypal-auth-algo"] || (raise MissingHeader, "No `paypal-auth-algo` header")
+    end
+
+    def download_and_cache_certificate(cert_url)
+      client.config.certs_cache.fetch("PaypalRestAPI.certificate.#{cert_url}") do
+        client.get(cert_url, headers: {"authorization" => nil}).http_body
+      end
+    end
+  end
+end

data/lib/paypal-api.rb

@@ -62,6 +62,18 @@ module PaypalAPI
       end
     end
 
+    #
+    # Verifies Webhook
+    #
+    # It requires one-time request to download and cache certificate.
+    # If local verification returns false it tries to verify webhook online.
+    #
+    # @see Client#verify_webhook
+    #
+    def verify_webhook(webhook_id:, headers:, raw_body:)
+      client.verify_webhook(webhook_id: webhook_id, headers: headers, raw_body: raw_body)
+    end
+
     #
     # @!macro [new] api_collection
     #   $0 APIs collection
@@ -206,6 +218,8 @@ require_relative "paypal-api/network_error_builder"
 require_relative "paypal-api/request"
 require_relative "paypal-api/request_executor"
 require_relative "paypal-api/response"
+require_relative "paypal-api/webhook_verifier"
+require_relative "paypal-api/webhook_verifier/certs_cache"
 require_relative "paypal-api/api_collections/authentication"
 require_relative "paypal-api/api_collections/authorized_payments"
 require_relative "paypal-api/api_collections/captured_payments"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: paypal-rest-api
 version: !ruby/object:Gem::Version
-  version: 0.0.4
+  version: 0.1.0
 platform: ruby
 authors:
 - Andrey Glushkov
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-08-25 00:00:00.000000000 Z
+date: 2024-08-30 00:00:00.000000000 Z
 dependencies: []
 description: PayPal REST API with no dependencies.
 email:
@@ -52,6 +52,8 @@ files:
 - lib/paypal-api/request_executor.rb
 - lib/paypal-api/response.rb
 - lib/paypal-api/version.rb
+- lib/paypal-api/webhook_verifier.rb
+- lib/paypal-api/webhook_verifier/certs_cache.rb
 - lib/paypal-rest-api.rb
 homepage: https://github.com/aglushkov/paypal-api
 licenses:
@@ -75,7 +77,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.17
+rubygems_version: 3.5.18
 signing_key:
 specification_version: 4
 summary: PayPal REST API