feat(client): add webhook support

Author: stainless-app[bot]

Gemfile

@@ -22,7 +22,7 @@ group :development, :test do
   gem "minitest-hooks"
   gem "minitest-proveit"
   gem "minitest-rg"
-  gem "standardwebhooks", "~> 1.0", github: "standard-webhooks/standard-webhooks", glob: "libraries/ruby/*.gemspec"
+  gem "standardwebhooks", "~> 1.0"
   gem "webmock"
 end
 

Gemfile.lock

@@ -8,13 +8,6 @@ GIT
       rbs
       syntax_tree (>= 2.0.1)
 
-GIT
-  remote: https://github.com/standard-webhooks/standard-webhooks.git
-  revision: a173a6c0125ca2b9245bf5ea3f1c61384ccc10a2
-  glob: libraries/ruby/*.gemspec
-  specs:
-    standardwebhooks (1.0.0)
-
 PATH
   remote: .
   specs:
@@ -150,6 +143,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)
@@ -223,7 +217,7 @@ DEPENDENCIES
   redcarpet
   rubocop
   sorbet
-  standardwebhooks (~> 1.0)!
+  standardwebhooks (~> 1.0)
   steep
   syntax_tree
   syntax_tree-rbs!

README.md

@@ -93,10 +93,10 @@ event = lithic.webhooks.parse_unsafe(request.body.read)
 
 #### Installing standardwebhooks (optional)
 
-To use signature verification, install from GitHub:
+To use signature verification, add the gem to your Gemfile:
 
 ```ruby
-gem "standardwebhooks", "~> 1.0", github: "standard-webhooks/standard-webhooks", glob: "libraries/ruby/*.gemspec"
+gem "standardwebhooks", "~> 1.0"
 ```
 
 ### Handling errors

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

@@ -9,7 +9,7 @@ class Webhooks
       # @param headers [Hash{String => String}] The webhook request headers
       # @param secret [String, nil] The webhook secret. If not provided, reads from LITHIC_WEBHOOK_SECRET environment variable.
       #
-      # @return [Lithic::Models::AccountHolderCreatedWebhookEvent, Lithic::Models::ParsedWebhookEvent::KYBPayload, Lithic::Models::ParsedWebhookEvent::KYCPayload, Lithic::Models::ParsedWebhookEvent::LegacyPayload, Lithic::Models::AccountHolderVerificationWebhookEvent, Lithic::Models::AccountHolderDocumentUpdatedWebhookEvent, Lithic::Models::AsaRequestWebhookEvent, 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::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::ThreeDSAuthentication, Lithic::Models::DisputeTransactionCreatedWebhookEvent, Lithic::Models::DisputeTransactionUpdatedWebhookEvent]
+      # @return [Lithic::ParsedWebhookEvent::Variants]
       #
       # @raise [ArgumentError] if secret is not provided and LITHIC_WEBHOOK_SECRET env var is not set
       # @raise [Lithic::Errors::MissingDependencyError] if the standardwebhooks gem is not installed

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:

rbi/lithic/resources/webhooks.rbi

@@ -71,7 +71,14 @@ module Lithic
           )
         )
       end
-      def parse(payload, headers:, secret: nil)
+      def parse(
+        # The raw webhook payload as a string
+        payload,
+        # The raw HTTP headers that came with the payload
+        headers:,
+        # The webhook signing secret
+        secret: nil
+      )
       end
 
       sig { params(payload: String).returns(Lithic::ParsedWebhookEvent::Variants) }

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,

test/lithic/resources/webhooks_test.rb

@@ -14,7 +14,6 @@ def test_parse_unsafe_webhook_payload
     }.to_json
 
     event = @lithic.webhooks.parse_unsafe(payload)
-    # Verify the event was parsed successfully
     assert(event)
     assert_equal("card.created", event.event_type)
   end
@@ -28,7 +27,6 @@ def test_parse_with_valid_signature
     payload = '{"event_type":"card.created","card_token":"test_card_token_123"}'
     timestamp = Time.now.to_i.to_s
 
-    # Generate a valid signature
     wh = StandardWebhooks::Webhook.new(secret)
     signature = wh.sign("test_msg_id", timestamp, payload)
 
@@ -38,12 +36,10 @@ def test_parse_with_valid_signature
       "webhook-signature" => signature
     }
 
-    # Should verify and return typed event
     event = @lithic.webhooks.parse(payload, headers: headers, secret: secret)
     assert(event)
     assert_equal(:"card.created", event.event_type)
 
-    # Verify we can pattern match on the typed event
     case event
     when Lithic::Models::CardCreatedWebhookEvent
       assert_equal("test_card_token_123", event.card_token)
@@ -52,6 +48,36 @@ def test_parse_with_valid_signature
     end
   end
 
+  def test_parse_with_invalid_signatures
+    skip("standardwebhooks gem not installed") unless gem_installed?("standardwebhooks")
+
+    require("standardwebhooks")
+
+    secret = "whsec_test_secret"
+    payload = '{"event_type":"card.created"}'
+    timestamp = Time.now.to_i.to_s
+
+    wh = StandardWebhooks::Webhook.new(secret)
+    signature = wh.sign("test_msg_id", timestamp, payload)
+
+    headers = {
+      "webhook-id" => "test_msg_id",
+      "webhook-timestamp" => timestamp,
+      "webhook-signature" => signature
+    }
+
+    bad_headers = [
+      headers.merge("webhook-id" => "bad"),
+      headers.merge("webhook-timestamp" => "0"),
+      headers.merge("webhook-signature" => wh.sign("test_msg_id", timestamp, "xxx"))
+    ]
+    bad_headers.each do |bad_header|
+      assert_raises(StandardWebhooks::WebhookVerificationError) do
+        @lithic.webhooks.parse(payload, headers: bad_header, secret: secret)
+      end
+    end
+  end
+
   def test_parse_with_env_var_secret
     skip("standardwebhooks gem not installed") unless gem_installed?("standardwebhooks")
 
@@ -61,7 +87,6 @@ def test_parse_with_env_var_secret
     payload = '{"event_type":"card.created","data":{"token":"test_token"}}'
     timestamp = Time.now.to_i.to_s
 
-    # Generate a valid signature
     wh = StandardWebhooks::Webhook.new(secret)
     signature = wh.sign("test_msg_id", timestamp, payload)
 
@@ -71,10 +96,8 @@ def test_parse_with_env_var_secret
       "webhook-signature" => signature
     }
 
-    # Set env var
     ENV["LITHIC_WEBHOOK_SECRET"] = secret
     begin
-      # Should use env var when secret not provided
       event = @lithic.webhooks.parse(payload, headers: headers)
       assert(event)
       assert_equal("card.created", event.event_type)
@@ -93,7 +116,6 @@ def test_parse_raises_when_secret_missing
       "webhook-signature" => "v1,invalid"
     }
 
-    # Ensure env var is not set
     ENV.delete("LITHIC_WEBHOOK_SECRET")
 
     error = assert_raises(ArgumentError) do
@@ -112,7 +134,6 @@ def test_verify_signature_with_valid_signature
     payload = '{"event_type":"card.created"}'
     timestamp = Time.now.to_i.to_s
 
-    # Generate a valid signature
     wh = StandardWebhooks::Webhook.new(secret)
     signature = wh.sign("test_msg_id", timestamp, payload)
 
@@ -122,14 +143,12 @@ def test_verify_signature_with_valid_signature
       "webhook-signature" => signature
     }
 
-    # Should not raise an error and returns the parsed JSON
     result = @lithic.webhooks.verify_signature(
       payload: payload,
       headers: headers,
       secret: secret
     )
 
-    # verify returns the parsed JSON content with symbolized keys
     assert_equal("card.created", result[:event_type])
   end
 
@@ -165,7 +184,6 @@ def test_verify_signature_with_env_var
     payload = '{"event_type":"card.created"}'
     timestamp = Time.now.to_i.to_s
 
-    # Generate a valid signature
     wh = StandardWebhooks::Webhook.new(secret)
     signature = wh.sign("test_msg_id", timestamp, payload)
 
@@ -175,10 +193,8 @@ def test_verify_signature_with_env_var
       "webhook-signature" => signature
     }
 
-    # Set env var
     ENV["LITHIC_WEBHOOK_SECRET"] = secret
     begin
-      # Should use env var when secret not provided
       result = @lithic.webhooks.verify_signature(payload: payload, headers: headers)
       assert_equal("card.created", result[:event_type])
     ensure