feat(client): add webhook support

Author: stainless-app[bot]

Gemfile.lock

@@ -21,6 +21,7 @@ PATH
     lithic (0.7.0)
       cgi
       connection_pool
+      standardwebhooks
 
 GEM
   remote: https://rubygems.org/
@@ -150,6 +151,7 @@ GEM
       rexml (>= 3.2.6)
       sorbet-static-and-runtime (>= 0.5.10187)
       thor (>= 0.19.2)
+    standardwebhooks (1.0.1)
     steep (1.10.0)
       activesupport (>= 5.1)
       concurrent-ruby (>= 1.1.10)

lib/lithic.rb

@@ -30,6 +30,7 @@
 
 # Gems.
 require "connection_pool"
+require "standardwebhooks"
 
 # Package files.
 require_relative "lithic/version"

lib/lithic/client.rb

@@ -23,6 +23,9 @@ class Client < Lithic::Internal::Transport::BaseClient
     # @return [String]
     attr_reader :api_key
 
+    # @return [String, nil]
+    attr_reader :webhook_secret
+
     # @return [Lithic::Resources::Accounts]
     attr_reader :accounts
 
@@ -149,6 +152,8 @@ def api_status(params = {})
     #
     # @param api_key [String, nil] Defaults to `ENV["LITHIC_API_KEY"]`
     #
+    # @param webhook_secret [String, nil] Defaults to `ENV["LITHIC_WEBHOOK_SECRET"]`
+    #
     # @param environment [:production, :sandbox, nil] Specifies the environment to use for the API.
     #
     # Each environment maps to a different base URL:
@@ -168,6 +173,7 @@ def api_status(params = {})
     # @param max_retry_delay [Float]
     def initialize(
       api_key: ENV["LITHIC_API_KEY"],
+      webhook_secret: ENV["LITHIC_WEBHOOK_SECRET"],
       environment: nil,
       base_url: ENV["LITHIC_BASE_URL"],
       max_retries: self.class::DEFAULT_MAX_RETRIES,
@@ -185,6 +191,7 @@ def initialize(
       end
 
       @api_key = api_key.to_s
+      @webhook_secret = webhook_secret&.to_s
 
       super(
         base_url: base_url,

lib/lithic/resources/webhooks.rb

@@ -32,8 +32,18 @@ def parse(payload, headers:, secret: nil)
       #
       # @param payload [String] The raw webhook payload as a string
       #
+      # @param headers [Hash{String=>String}] The raw HTTP headers that came with the payload
+      #
+      # @param key [String, nil] The webhook signing key
+      #
       # @return [Lithic::Models::AccountHolderCreatedWebhookEvent, Lithic::Models::ParsedWebhookEvent::KYBPayload, Lithic::Models::ParsedWebhookEvent::KYCPayload, Lithic::Models::ParsedWebhookEvent::LegacyPayload, Lithic::Models::AccountHolderVerificationWebhookEvent, Lithic::Models::AccountHolderDocumentUpdatedWebhookEvent, Lithic::Models::CardAuthorizationApprovalRequestWebhookEvent, Lithic::Models::TokenizationDecisioningRequestWebhookEvent, Lithic::Models::AuthRulesBacktestReportCreatedWebhookEvent, Lithic::Models::BalanceUpdatedWebhookEvent, Lithic::Models::BookTransferTransactionCreatedWebhookEvent, Lithic::Models::BookTransferTransactionUpdatedWebhookEvent, Lithic::Models::CardCreatedWebhookEvent, Lithic::Models::CardConvertedWebhookEvent, Lithic::Models::CardRenewedWebhookEvent, Lithic::Models::CardReissuedWebhookEvent, Lithic::Models::CardShippedWebhookEvent, Lithic::Models::CardUpdatedWebhookEvent, Lithic::Models::CardTransactionUpdatedWebhookEvent, Lithic::Models::CardTransactionEnhancedDataCreatedWebhookEvent, Lithic::Models::CardTransactionEnhancedDataUpdatedWebhookEvent, Lithic::Models::DigitalWalletTokenizationApprovalRequestWebhookEvent, Lithic::Models::DigitalWalletTokenizationResultWebhookEvent, Lithic::Models::DigitalWalletTokenizationTwoFactorAuthenticationCodeWebhookEvent, Lithic::Models::DigitalWalletTokenizationTwoFactorAuthenticationCodeSentWebhookEvent, Lithic::Models::DigitalWalletTokenizationUpdatedWebhookEvent, Lithic::Models::DisputeUpdatedWebhookEvent, Lithic::Models::DisputeEvidenceUploadFailedWebhookEvent, Lithic::Models::ExternalBankAccountCreatedWebhookEvent, Lithic::Models::ExternalBankAccountUpdatedWebhookEvent, Lithic::Models::ExternalPaymentCreatedWebhookEvent, Lithic::Models::ExternalPaymentUpdatedWebhookEvent, Lithic::Models::FinancialAccountCreatedWebhookEvent, Lithic::Models::FinancialAccountUpdatedWebhookEvent, Lithic::Models::FundingEventCreatedWebhookEvent, Lithic::Models::LoanTapeCreatedWebhookEvent, Lithic::Models::LoanTapeUpdatedWebhookEvent, Lithic::Models::ManagementOperationCreatedWebhookEvent, Lithic::Models::ManagementOperationUpdatedWebhookEvent, Lithic::Models::InternalTransactionCreatedWebhookEvent, Lithic::Models::InternalTransactionUpdatedWebhookEvent, Lithic::Models::NetworkTotalCreatedWebhookEvent, Lithic::Models::NetworkTotalUpdatedWebhookEvent, Lithic::Models::PaymentTransactionCreatedWebhookEvent, Lithic::Models::PaymentTransactionUpdatedWebhookEvent, Lithic::Models::SettlementReportUpdatedWebhookEvent, Lithic::Models::StatementsCreatedWebhookEvent, Lithic::Models::ThreeDSAuthenticationCreatedWebhookEvent, Lithic::Models::ThreeDSAuthenticationUpdatedWebhookEvent, Lithic::Models::ThreeDSAuthenticationChallengeWebhookEvent, Lithic::Models::TokenizationApprovalRequestWebhookEvent, Lithic::Models::TokenizationResultWebhookEvent, Lithic::Models::TokenizationTwoFactorAuthenticationCodeWebhookEvent, Lithic::Models::TokenizationTwoFactorAuthenticationCodeSentWebhookEvent, Lithic::Models::TokenizationUpdatedWebhookEvent, Lithic::Models::ThreeDSAuthenticationApprovalRequestWebhookEvent, Lithic::Models::DisputeTransactionCreatedWebhookEvent, Lithic::Models::DisputeTransactionUpdatedWebhookEvent]
-      def parse_unsafe(payload)
+      def parse_unsafe(payload, headers:, key: @client.webhook_secret)
+        if key.nil?
+          raise ArgumentError.new("Cannot verify a webhook without a key on either the client's webhook_secret or passed in as an argument")
+        end
+
+        ::StandardWebhooks::Webhook.new(key).verify(payload, headers)
+
         parsed = JSON.parse(payload, symbolize_names: true)
         Lithic::Internal::Type::Converter.coerce(Lithic::Models::ParsedWebhookEvent, parsed)
       end

lithic.gemspec

@@ -26,4 +26,5 @@ Gem::Specification.new do |s|
   s.extra_rdoc_files = ["README.md"]
   s.add_dependency "cgi"
   s.add_dependency "connection_pool"
+  s.add_dependency "standardwebhooks"
 end

rbi/lithic/client.rbi

@@ -22,6 +22,9 @@ module Lithic
     sig { returns(String) }
     attr_reader :api_key
 
+    sig { returns(T.nilable(String)) }
+    attr_reader :webhook_secret
+
     sig { returns(Lithic::Resources::Accounts) }
     attr_reader :accounts
 
@@ -142,6 +145,7 @@ module Lithic
     sig do
       params(
         api_key: T.nilable(String),
+        webhook_secret: T.nilable(String),
         environment: T.nilable(T.any(Symbol, String)),
         base_url: T.nilable(String),
         max_retries: Integer,
@@ -153,6 +157,8 @@ module Lithic
     def self.new(
       # Defaults to `ENV["LITHIC_API_KEY"]`
       api_key: ENV["LITHIC_API_KEY"],
+      # Defaults to `ENV["LITHIC_WEBHOOK_SECRET"]`
+      webhook_secret: ENV["LITHIC_WEBHOOK_SECRET"],
       # Specifies the environment to use for the API.
       #
       # Each environment maps to a different base URL:

sig/lithic/client.rbs

@@ -15,6 +15,8 @@ module Lithic
 
     attr_reader api_key: String
 
+    attr_reader webhook_secret: String?
+
     attr_reader accounts: Lithic::Resources::Accounts
 
     attr_reader account_holders: Lithic::Resources::AccountHolders
@@ -91,6 +93,7 @@ module Lithic
 
     def initialize: (
       ?api_key: String?,
+      ?webhook_secret: String?,
       ?environment: :production | :sandbox | nil,
       ?base_url: String?,
       ?max_retries: Integer,