feat(api): add webhook schemas to SDKs - add parse and parse_unsafe

chore: replace custom webhook signature verification with standardwebhooks

Author: stainless-app[bot]

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 176
 openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/lithic%2Flithic-abe6a4f82f696099fa8ecb1cc44f08979e17d56578ae7ea68b0e9182e21df508.yml
 openapi_spec_hash: d2ce51592a9a234c6f34a1168a31f91f
-config_hash: 739714a3fead0b26ee3a3b7bc51081f6
+config_hash: 2b2786c821f62db49cc630ba45329336

Gemfile

@@ -22,6 +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 "webmock"
 end
 

Gemfile.lock

@@ -8,6 +8,13 @@ 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:
@@ -214,6 +221,7 @@ DEPENDENCIES
   redcarpet
   rubocop
   sorbet
+  standardwebhooks (~> 1.0)!
   steep
   syntax_tree
   syntax_tree-rbs!

README.md

@@ -64,6 +64,41 @@ if page.next_page?
 end
 ```
 
+### Webhooks
+
+Lithic uses webhooks to notify your application when events happen. The library provides signature verification via the optional `standardwebhooks` gem.
+
+#### Parsing and verifying webhooks
+
+```ruby
+# Verifies signature and returns typed event
+event = lithic.webhooks.parse(
+  request.body.read,
+  headers: request.headers,
+  secret: ENV["LITHIC_WEBHOOK_SECRET"] # optional, reads from env by default
+)
+
+case event
+when Lithic::Models::CardCreatedWebhookEvent
+  puts("Card created: #{event.data.token}")
+end
+```
+
+#### Parsing without verification
+
+```ruby
+# Parse only - skips signature verification (not recommended for production)
+event = lithic.webhooks.parse_unsafe(request.body.read)
+```
+
+#### Installing standardwebhooks (optional)
+
+To use signature verification, install from GitHub:
+
+```ruby
+gem "standardwebhooks", "~> 1.0", github: "standard-webhooks/standard-webhooks", glob: "libraries/ruby/*.gemspec"
+```
+
 ### Handling errors
 
 When the library is unable to connect to the API, or if the API returns a non-success status code (i.e., 4xx or 5xx response), a subclass of `Lithic::Errors::APIError` will be thrown:

lib/lithic.rb

@@ -119,6 +119,9 @@ class Client < Lithic::Internal::Transport::BaseClient
     # @return [Lithic::Resources::AccountActivity]
     attr_reader :account_activity
 
+    # @return [Lithic::Resources::Webhooks]
+    attr_reader :webhooks
+
     # Status of api
     #
     # @overload api_status(request_options: {})
@@ -225,6 +228,7 @@ def initialize(
       @fraud = Lithic::Resources::Fraud.new(client: self)
       @network_programs = Lithic::Resources::NetworkPrograms.new(client: self)
       @account_activity = Lithic::Resources::AccountActivity.new(client: self)
+      @webhooks = Lithic::Resources::Webhooks.new(client: self)
     end
   end
 end

lib/lithic/client.rb

@@ -224,5 +224,20 @@ class RateLimitError < Lithic::Errors::APIStatusError
     class InternalServerError < Lithic::Errors::APIStatusError
       HTTP_STATUS = (500..)
     end
+
+    class MissingDependencyError < Lithic::Errors::Error
+      # @api private
+      #
+      # @param gem_name [String]
+      # @param feature [String]
+      def initialize(gem_name:, feature:)
+        message = [
+          "The '#{gem_name}' gem is required to use #{feature}.",
+          "Install it with: gem install #{gem_name}",
+          "Or add it to your Gemfile: gem '#{gem_name}'"
+        ].join("\n")
+        super(message)
+      end
+    end
   end
 end