mobiscroll-connect 1.5.1 → 1.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a5b667cc604c98500160cd034837d4ef9b097ef5a08e50ff9ab75ec451f41d5f
-  data.tar.gz: b3d758a7b2cc387d570526a6ddae75ce216d12082ee156b341343942362e4f3c
+  metadata.gz: bfda16db0b33649065d21a3df62ae7f3b6962adaa0e57fd11944b5e0edce780f
+  data.tar.gz: 476dd4536d5bae00d3e169d26c30bb98ac3ab24aa82fe4b4b65a47b55cb57bea
 SHA512:
-  metadata.gz: debeb4453999f74a080e45b5e1c1ea6ade00a6a3f370c665be12c2ce1e994244c7256738734ac00fa893cb754dd132a620aa63dc292fcb722f66b348e16cb455
-  data.tar.gz: 20c2e49dec99acc7fe35b4cf42b2a7a084a00d23ea86f802cd7714d5fbcf5a82c35c09cf57997d99ca688b3e6e16b5e8dace0ade00e64b16feaaa25eb32828f7
+  metadata.gz: 6ffcf4cddf3cfafe432cb53bff0ebda0b0f8af4fc9d113e18fd5540cddc3328fe32d40d47b5ce8922cb32e4e758198e24a804c939e4676aa842991ebe98334e5
+  data.tar.gz: 35f100a37e7fdc727c8bf824726c907100286d41b4738e7aa78fe2d4f9e9fe05bdcdeef296f3898ecbe14193842957132e1bc2ccddcb8ab86448015ff49a9232

data/CHANGELOG.md

@@ -2,7 +2,15 @@
 
 All notable changes to the Mobiscroll Connect Ruby SDK (RubyGems: `mobiscroll-connect`) are documented in this file.
 
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this SDK follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html). SDKs in this monorepo version independently, so this file covers the Ruby SDK only.
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this SDK's major.minor always matches the Connect API's (for example API 1.5.x → SDK 1.5.x): each release bumps only the patch, including releases with breaking changes. Patch numbers are independent per SDK, so this file covers the Ruby SDK only.
+
+## [1.6.0] — 2026-10-08
+
+### Added
+
+- `webhooks.verify_webhook` checks a delivery's Ed25519 signature and timestamp and returns the parsed `WebhookDelivery`, or raises `WebhookVerificationError`. It fetches and caches the public keys from `/.well-known/webhook-keys` and re-fetches them once before rejecting, so key rotations need no action.
+- `webhook_public_key` client option: a pinned key, used only when the keys endpoint cannot be reached.
+- `Mobiscroll::Connect.verify_webhook_signature` for verifying against keys you supply, with no fetching.
 
 ## [1.5.1] — 2026-09-22
 

data/README.md

@@ -4,7 +4,7 @@ Ruby client for [Mobiscroll Connect](https://mobiscroll.com/connect), the calend
 
 [![RubyGems](https://img.shields.io/gem/v/mobiscroll-connect?label=RubyGems)](https://rubygems.org/gems/mobiscroll-connect)
 
-**[RubyGems](https://rubygems.org/gems/mobiscroll-connect)** · **[Documentation](https://mobiscroll.com/docs/connect/ruby-sdk)** · **[Changelog](CHANGELOG.md)** · **[Source](https://github.com/acidb/mobiscroll-connect-sdks/tree/main/sdks/ruby)**
+**[RubyGems](https://rubygems.org/gems/mobiscroll-connect)** · **[Documentation](https://mobiscroll.com/docs/connect/ruby-sdk)** · **[Changelog](https://github.com/acidb/mobiscroll-connect-sdks/blob/main/sdks/ruby/CHANGELOG.md)** · **[Source](https://github.com/acidb/mobiscroll-connect-sdks/tree/main/sdks/ruby)**
 
 ## Installation
 
@@ -98,6 +98,8 @@ The SDK automatically refreshes expired access tokens. When a request returns 40
 
 Concurrent 401s share a single in-flight refresh — only one `POST /oauth/token` is ever issued per `Client` instance at a time.
 
+**Running more than one instance.** The single in-flight refresh above is per `Client` instance. The SDK does not coordinate across processes — separate containers, cluster workers or serverless invocations each refresh from the tokens they hold in memory. Connect accepts concurrent refreshes of the same token, but refreshing with a copy that is two or more refreshes out of date revokes the user's authorization. Persist refreshed tokens to storage every instance reads, and call `client.set_credentials(...)` with the current tokens when a process starts a job or handles a request. See [Refreshing from several instances](https://mobiscroll.com/docs/connect/api/oauth#concurrent-refresh).
+
 To persist refreshed tokens (e.g., back to a session or database):
 
 ```ruby
@@ -197,6 +199,40 @@ client.webhooks.unsubscribe_webhook(
 )
 ```
 
+### Verify webhook deliveries
+
+Every delivery to your webhook URL is signed. `verify_webhook` checks the signature and the timestamp, then returns the parsed `WebhookDelivery`, or raises `WebhookVerificationError`. Pass the **raw** request body: a JSON body parser that runs first changes the bytes and every check fails.
+
+```ruby
+post '/webhooks/mobiscroll' do
+  begin
+    delivery = client.webhooks.verify_webhook(request.body.read, request.env)
+  rescue Mobiscroll::Connect::WebhookVerificationError => e
+    # 503 lets Connect retry when the keys could not be loaded; 401 is final.
+    halt(e.reason == 'no_public_keys' ? 503 : 401)
+  end
+  handle_delivery(delivery)
+  status 204
+end
+```
+
+`headers` can be a Hash with any key casing, a Rack env (`HTTP_WEBHOOK_ID` keys), or Rails' `request.headers` (pass `request.raw_post` as the body in Rails).
+
+The public keys are fetched from `https://connect.mobiscroll.com/.well-known/webhook-keys` on the first delivery and cached for the whole process as the endpoint's `Cache-Control` allows. If no signature matches, the keys are fetched again (at most once a minute) before the delivery is rejected, so key rotations need no action on your side.
+
+If your handler cannot make outbound requests, pin the key. `webhook_public_key` is used only when the keys endpoint cannot be reached; it stops working when Mobiscroll retires that key, so you must replace it on every rotation.
+
+```ruby
+client = Mobiscroll::Connect::Client.new(
+  client_id:          ENV['MOBISCROLL_CLIENT_ID'],
+  client_secret:      ENV['MOBISCROLL_CLIENT_SECRET'],
+  redirect_uri:       ENV['MOBISCROLL_REDIRECT_URI'],
+  webhook_public_key: ENV['MOBISCROLL_WEBHOOK_PUBLIC_KEY'] # whpk_...
+)
+```
+
+To check against keys you supply, with no fetching, call `Mobiscroll::Connect.verify_webhook_signature(raw_body, headers, ['whpk_...'])`. It raises `WebhookVerificationError` and returns `nil`. See [Verifying deliveries](https://mobiscroll.com/docs/connect/api/webhooks#verifying-deliveries).
+
 ## Error handling
 
 All errors are subclasses of `Mobiscroll::Connect::Error`:
@@ -229,6 +265,7 @@ end
 | `RateLimitError` | 429 | `retry_after` (seconds) |
 | `ServerError` | 5xx | `status_code` |
 | `NetworkError` | transport | `cause` |
+| `WebhookVerificationError` | — (from `verify_webhook`) | `reason` |
 
 ## Minimal demo app
 

data/lib/mobiscroll/connect/client.rb

@@ -7,14 +7,15 @@ module Mobiscroll
 
       def initialize(client_id:, client_secret:, redirect_uri:,
                      base_url: DEFAULT_BASE_URL, timeout: DEFAULT_TIMEOUT,
-                     on_tokens_refreshed: nil)
+                     on_tokens_refreshed: nil, webhook_public_key: nil)
         @config = Config.new(
           client_id: client_id,
           client_secret: client_secret,
           redirect_uri: redirect_uri,
           base_url: base_url,
           timeout: timeout,
-          on_tokens_refreshed: on_tokens_refreshed
+          on_tokens_refreshed: on_tokens_refreshed,
+          webhook_public_key: webhook_public_key
         )
         @api_client = ApiClient.new(@config)
         @auth = Resources::Auth.new(@config, @api_client)

data/lib/mobiscroll/connect/config.rb

@@ -6,12 +6,14 @@ module Mobiscroll
     DEFAULT_TIMEOUT = 30
 
     class Config
-      attr_reader :client_id, :client_secret, :redirect_uri, :base_url, :timeout
+      # `webhook_public_key` is a pinned `whpk_` key, used by Webhooks#verify_webhook only when
+      # the keys endpoint cannot be reached; it stops verifying once Mobiscroll retires that key.
+      attr_reader :client_id, :client_secret, :redirect_uri, :base_url, :timeout, :webhook_public_key
       attr_accessor :on_tokens_refreshed
 
       def initialize(client_id:, client_secret:, redirect_uri:,
                      base_url: DEFAULT_BASE_URL, timeout: DEFAULT_TIMEOUT,
-                     on_tokens_refreshed: nil)
+                     on_tokens_refreshed: nil, webhook_public_key: nil)
         raise Error, 'client_id is required' if client_id.nil? || client_id.empty?
         raise Error, 'client_secret is required' if client_secret.nil? || client_secret.empty?
         raise Error, 'redirect_uri is required' if redirect_uri.nil? || redirect_uri.empty?
@@ -22,6 +24,7 @@ module Mobiscroll
         @base_url = base_url
         @timeout = timeout
         @on_tokens_refreshed = on_tokens_refreshed
+        @webhook_public_key = webhook_public_key
       end
     end
   end

data/lib/mobiscroll/connect/errors.rb

@@ -78,6 +78,19 @@ module Mobiscroll
       end
     end
 
+    # Raised when a webhook delivery fails verification. Respond with a 4xx and do not process it.
+    #
+    # +reason+ is one of 'missing_headers', 'invalid_timestamp', 'timestamp_out_of_tolerance',
+    # 'no_public_keys', 'no_matching_signature' or 'invalid_payload'.
+    class WebhookVerificationError < Error
+      attr_reader :reason
+
+      def initialize(message = 'Webhook verification failed', reason: nil)
+        super(message, code: 'WEBHOOK_VERIFICATION_ERROR')
+        @reason = reason
+      end
+    end
+
     # Maps an HTTP response (status + body hash + headers) to the matching
     # typed error. Returns nil for 2xx responses.
     def self.map_response_error(status, body, headers)

data/lib/mobiscroll/connect/models.rb

@@ -242,6 +242,52 @@ module Mobiscroll
       end
     end
 
+    # A changed event in a webhook delivery: every CalendarEvent field plus `change_type`
+    # ('created', 'updated' or 'deleted').
+    WebhookEvent = Struct.new(*CalendarEvent.members, :change_type, keyword_init: true) do
+      def self.from_h(hash)
+        return nil if hash.nil?
+
+        new(**CalendarEvent.from_h(hash).to_h, change_type: hash['changeType'] || hash[:changeType])
+      end
+    end
+
+    # `metadata` of a webhook delivery.
+    WebhookDeliveryMetadata = Struct.new(:channel_id, :event_count, :is_initial_sync, keyword_init: true) do
+      def self.from_h(hash)
+        return nil if hash.nil?
+
+        key = 'isInitialSync'
+        new(
+          channel_id: hash['channelId'] || hash[:channelId],
+          event_count: hash['eventCount'] || hash[:eventCount],
+          is_initial_sync: hash.key?(key) ? hash[key] : hash[key.to_sym]
+        )
+      end
+    end
+
+    # A verified webhook delivery, returned by Webhooks#verify_webhook. `change_type` is
+    # 'created', 'updated', 'deleted' or 'mixed'; `timestamp` is the ISO 8601 time Connect
+    # processed the change.
+    WebhookDelivery = Struct.new(
+      :provider, :user_id, :calendar_id, :events, :change_type, :timestamp, :metadata, keyword_init: true
+    ) do
+      def self.from_h(hash)
+        return nil if hash.nil?
+
+        metadata = hash['metadata'] || hash[:metadata]
+        new(
+          provider: hash['provider'] || hash[:provider],
+          user_id: hash['userId'] || hash[:userId],
+          calendar_id: hash['calendarId'] || hash[:calendarId],
+          events: Array(hash['events'] || hash[:events]).filter_map { |e| WebhookEvent.from_h(e) if e.is_a?(Hash) },
+          change_type: hash['changeType'] || hash[:changeType],
+          timestamp: hash['timestamp'] || hash[:timestamp],
+          metadata: metadata.is_a?(Hash) ? WebhookDeliveryMetadata.from_h(metadata) : nil
+        )
+      end
+    end
+
     # Response from Webhooks#unsubscribe_webhook. `success` is true whenever the local
     # mapping was removed, even if the provider-side unsubscribe itself failed — `message`
     # explains what happened in that case.

data/lib/mobiscroll/connect/resources/webhooks.rb

@@ -1,12 +1,16 @@
 # frozen_string_literal: true
 
 require 'json'
+require 'uri'
 
 module Mobiscroll
   module Connect
     module Resources
       class Webhooks
-        def initialize(_config, api_client)
+        RETRYABLE_REASONS = %w[no_matching_signature no_public_keys].freeze
+
+        def initialize(config, api_client)
+          @config = config
           @api_client = api_client
         end
 
@@ -36,6 +40,62 @@ module Mobiscroll
           parsed = @api_client.post('/unsubscribe-webhook', body: JSON.generate(body))
           UnsubscribeWebhookResponse.from_h(parsed)
         end
+
+        # Verifies that a webhook delivery came from Mobiscroll Connect, and parses it.
+        #
+        # Fetches the public keys from `/.well-known/webhook-keys` on first use and caches them for
+        # the whole process, refreshing them as the endpoint's `Cache-Control` allows. When no
+        # signature matches, it re-fetches the keys once (at most once a minute) before rejecting,
+        # so a key rotation never rejects genuine deliveries. `webhook_public_key` from the config
+        # is used only when the endpoint cannot be reached.
+        #
+        # `payload` is the raw request body String, exactly as received; not a parsed Hash.
+        # `headers` is a Hash (any key casing) or a Rack env / Rails `request.headers`.
+        #
+        # Returns a WebhookDelivery. Raises WebhookVerificationError when the delivery is not
+        # genuine; respond with a 4xx.
+        #
+        #   post '/webhooks/mobiscroll' do
+        #     delivery = client.webhooks.verify_webhook(request.body.read, request.env)
+        #     handle_delivery(delivery)
+        #     status 204
+        #   rescue Mobiscroll::Connect::WebhookVerificationError
+        #     halt 401
+        #   end
+        def verify_webhook(payload, headers)
+          store = WebhookKeyStore.for_url(URI.join(@config.base_url, WEBHOOK_KEYS_PATH).to_s)
+
+          begin
+            Connect.verify_webhook_signature(payload, headers, keys_or_pinned(store.keys))
+          rescue WebhookVerificationError => e
+            raise unless RETRYABLE_REASONS.include?(e.reason) && store.can_refetch?
+
+            store.refresh
+            Connect.verify_webhook_signature(payload, headers, keys_or_pinned(store.keys))
+          end
+
+          parse_delivery(payload)
+        end
+
+        private
+
+        # The pinned key is never merged with fetched keys: after an emergency rotation a pinned
+        # retired key must stop verifying.
+        def keys_or_pinned(keys)
+          pinned = @config.webhook_public_key
+          keys.empty? && pinned && !pinned.empty? ? [pinned] : keys
+        end
+
+        def parse_delivery(payload)
+          parsed = begin
+            JSON.parse(payload.dup.force_encoding(Encoding::UTF_8))
+          rescue JSON::ParserError, EncodingError
+            nil
+          end
+          return WebhookDelivery.from_h(parsed) if parsed.is_a?(Hash)
+
+          raise WebhookVerificationError.new('Webhook payload is not a JSON object', reason: 'invalid_payload')
+        end
       end
     end
   end

data/lib/mobiscroll/connect/version.rb

@@ -2,6 +2,6 @@
 
 module Mobiscroll
   module Connect
-    VERSION = '1.5.1'
+    VERSION = '1.6.0'
   end
 end

data/lib/mobiscroll/connect/webhook_verification.rb

@@ -0,0 +1,250 @@
+# frozen_string_literal: true
+
+require 'base64'
+require 'faraday'
+require 'json'
+require 'openssl'
+
+module Mobiscroll
+  module Connect
+    WEBHOOK_TOLERANCE_SECONDS = 300
+    WEBHOOK_KEYS_PATH = '/.well-known/webhook-keys'
+
+    # Verifies the Standard Webhooks `v1a` (Ed25519) signature of a Mobiscroll Connect delivery
+    # against the given public keys, without fetching anything.
+    #
+    # Use it with a pinned key in handlers that cannot make outbound requests. Otherwise prefer
+    # `client.webhooks.verify_webhook`, which fetches and refreshes the keys for you.
+    #
+    # `payload` is the raw request body String, exactly as received. `headers` is a Hash (any
+    # key casing, Array values take the first) or a Rack env / Rails `request.headers`, where
+    # `HTTP_WEBHOOK_ID`-style keys are matched too. `public_keys` are `whpk_` keys; the delivery
+    # is genuine if any signature verifies against any key. `now` is the current Unix time in
+    # seconds, defaulting to the system clock.
+    #
+    # Returns nil. Raises WebhookVerificationError when the delivery is not genuine or cannot
+    # be checked.
+    #
+    #   Mobiscroll::Connect.verify_webhook_signature(
+    #     request.body.read, request.env, [ENV.fetch('MOBISCROLL_WEBHOOK_PUBLIC_KEY')]
+    #   )
+    def self.verify_webhook_signature(payload, headers, public_keys,
+                                      tolerance_seconds: WEBHOOK_TOLERANCE_SECONDS, now: nil)
+      WebhookSignature.verify(payload, headers, public_keys, tolerance_seconds: tolerance_seconds, now: now)
+      nil
+    end
+
+    # @api private
+    module WebhookSignature
+      PUBLIC_KEY_PREFIX = 'whpk_'
+      SIGNATURE_VERSION = 'v1a'
+      # DER SubjectPublicKeyInfo header for an Ed25519 key; `OpenSSL::PKey.new_raw_public_key`
+      # needs openssl gem 3.2+, which Ruby 3.2 does not bundle.
+      ED25519_SPKI_PREFIX = ['302a300506032b6570032100'].pack('H*').freeze
+
+      module_function
+
+      def verify(payload, headers, public_keys, tolerance_seconds:, now:)
+        unless payload.is_a?(String)
+          raise WebhookVerificationError.new(
+            'Pass the raw request body as a String, not a parsed object', reason: 'invalid_payload'
+          )
+        end
+
+        id = read_header(headers, 'webhook-id')
+        timestamp = read_header(headers, 'webhook-timestamp')
+        signature_header = read_header(headers, 'webhook-signature')
+        if [id, timestamp, signature_header].any? { |value| value.nil? || value.empty? }
+          raise WebhookVerificationError.new(
+            'Missing webhook-id, webhook-timestamp or webhook-signature header', reason: 'missing_headers'
+          )
+        end
+
+        check_timestamp(timestamp, tolerance_seconds, now || Time.now.to_i)
+
+        keys = Array(public_keys).filter_map { |key| parse_public_key(key) }
+        if keys.empty?
+          raise WebhookVerificationError.new('No valid webhook public keys available', reason: 'no_public_keys')
+        end
+
+        signed_content = "#{id}.#{timestamp}.".b << payload.b
+        return if signature_header.split(/ /).any? { |entry| entry_matches?(entry, signed_content, keys) }
+
+        raise WebhookVerificationError.new('No webhook signature matched', reason: 'no_matching_signature')
+      end
+
+      def check_timestamp(timestamp, tolerance_seconds, now)
+        unless timestamp.match?(/\A\d+\z/)
+          raise WebhookVerificationError.new('Invalid webhook-timestamp header', reason: 'invalid_timestamp')
+        end
+        return if (now - timestamp.to_i).abs <= tolerance_seconds
+
+        raise WebhookVerificationError.new(
+          'Webhook timestamp is outside the allowed tolerance', reason: 'timestamp_out_of_tolerance'
+        )
+      end
+
+      def read_header(headers, name)
+        return nil unless headers.respond_to?(:each)
+
+        rack_name = "HTTP_#{name.upcase.tr('-', '_')}"
+        headers.each do |key, value|
+          next unless key.to_s.casecmp?(name) || key.to_s.casecmp?(rack_name)
+
+          value = value.first if value.is_a?(Array)
+          return value&.to_s&.b
+        end
+        nil
+      end
+
+      def parse_public_key(value)
+        return nil unless value.is_a?(String)
+
+        raw = Base64.decode64(value.strip.delete_prefix(PUBLIC_KEY_PREFIX))
+        return nil unless raw.bytesize == 32
+
+        OpenSSL::PKey.read(ED25519_SPKI_PREFIX + raw)
+      rescue OpenSSL::PKey::PKeyError
+        nil
+      end
+
+      def entry_matches?(entry, signed_content, keys)
+        version, separator, encoded = entry.partition(',')
+        return false if separator.empty? || version != SIGNATURE_VERSION
+
+        signature = Base64.decode64(encoded)
+        return false unless signature.bytesize == 64
+
+        keys.any? do |key|
+          key.verify(nil, signature, signed_content)
+        rescue OpenSSL::PKey::PKeyError
+          false
+        end
+      end
+    end
+    private_constant :WebhookSignature
+
+    # Process-wide cache of the keys published at one keys URL, shared by every client instance.
+    # Follows the endpoint's `Cache-Control`, re-fetches at most once a minute, and keeps the last
+    # good keys when a fetch fails. Concurrent callers share one in-flight fetch.
+    #
+    # @api private
+    class WebhookKeyStore
+      DEFAULT_MAX_AGE = 60 * 60
+      MAX_MAX_AGE = 24 * 60 * 60
+      MIN_REFETCH_INTERVAL = 60
+      FETCH_TIMEOUT = 10
+
+      @stores = {}
+      @stores_lock = Mutex.new
+
+      class << self
+        def for_url(url)
+          @stores_lock.synchronize { @stores[url] ||= new(url) }
+        end
+
+        # Clears every cached key set; for tests.
+        def reset!
+          @stores_lock.synchronize { @stores.clear }
+        end
+      end
+
+      def initialize(url)
+        @url = url
+        @keys = [].freeze
+        @fetched_at = nil
+        @last_attempt_at = nil
+        @max_age = DEFAULT_MAX_AGE
+        @in_flight = false
+        @lock = Mutex.new
+        @cond = ConditionVariable.new
+      end
+
+      # The current keys, fetching them first when they are missing or stale and a fetch is allowed.
+      def keys
+        fetch_if { |now| stale?(now) && can_refetch_at?(now) }
+        @lock.synchronize { @keys }
+      end
+
+      def can_refetch?
+        @lock.synchronize { can_refetch_at?(Time.now.to_f) }
+      end
+
+      # Fetches the keys unless a fetch was attempted in the last minute; joins one in flight.
+      def refresh
+        fetch_if { |now| can_refetch_at?(now) }
+      end
+
+      private
+
+      def stale?(now)
+        @fetched_at.nil? || now - @fetched_at > @max_age
+      end
+
+      def can_refetch_at?(now)
+        @last_attempt_at.nil? || now - @last_attempt_at >= MIN_REFETCH_INTERVAL
+      end
+
+      # Starts a fetch when the block allows it, or waits for the one already in flight; the
+      # decision and the in-flight flag are taken under one lock so callers never fetch twice.
+      def fetch_if
+        @lock.synchronize do
+          if @in_flight
+            @cond.wait(@lock) while @in_flight
+            return
+          end
+          now = Time.now.to_f
+          return unless yield(now)
+
+          @in_flight = true
+          @last_attempt_at = now
+        end
+
+        result = nil
+        begin
+          result = fetch_keys
+        ensure
+          @lock.synchronize do
+            if result
+              @keys, @max_age = result
+              @fetched_at = Time.now.to_f
+            end
+            @in_flight = false
+            @cond.broadcast
+          end
+        end
+      end
+
+      # Returns [keys, max_age], or nil when the fetch fails or yields no usable key. Uses a plain
+      # connection: the keys endpoint is public and must never go through the token-refresh path.
+      def fetch_keys
+        response = Faraday.new(request: { timeout: FETCH_TIMEOUT, open_timeout: FETCH_TIMEOUT }).get(@url) do |req|
+          req.headers['Accept'] = 'application/json'
+        end
+        return nil unless response.success?
+
+        parsed = JSON.parse(response.body.to_s)
+        keys = Array(parsed.is_a?(Hash) ? parsed['keys'] : nil).filter_map { |entry| usable_key(entry) }
+        keys.empty? ? nil : [keys.freeze, parse_max_age(response.headers['cache-control'])]
+      rescue StandardError
+        nil
+      end
+
+      def usable_key(entry)
+        return nil unless entry.is_a?(Hash)
+
+        key = entry['key']
+        alg = entry['alg'].to_s
+        return nil unless key.is_a?(String) && key.start_with?(WebhookSignature::PUBLIC_KEY_PREFIX)
+        return nil unless alg.empty? || alg.casecmp?('ed25519')
+
+        key
+      end
+
+      def parse_max_age(cache_control)
+        match = /max-age=(\d+)/i.match(cache_control.to_s)
+        match ? [match[1].to_i, MAX_MAX_AGE].min : DEFAULT_MAX_AGE
+      end
+    end
+  end
+end

data/lib/mobiscroll/connect.rb

@@ -6,6 +6,7 @@ require_relative 'connect/provider'
 require_relative 'connect/config'
 require_relative 'connect/models'
 require_relative 'connect/api_client'
+require_relative 'connect/webhook_verification'
 require_relative 'connect/resources/auth'
 require_relative 'connect/resources/calendars'
 require_relative 'connect/resources/events'

data/mobiscroll-connect.gemspec

@@ -22,7 +22,7 @@ Gem::Specification.new do |spec|
 
   spec.metadata = {
     'homepage_uri' => spec.homepage,
-    'source_code_uri' => 'https://github.com/acidb/mobiscroll-connect-sdks',
+    'source_code_uri' => 'https://github.com/acidb/mobiscroll-connect-sdks/tree/main/sdks/ruby',
     'documentation_uri' => 'https://mobiscroll.com/docs/connect/ruby-sdk',
     'bug_tracker_uri' => 'https://github.com/acidb/mobiscroll-connect-sdks/issues',
     'changelog_uri' => 'https://github.com/acidb/mobiscroll-connect-sdks/blob/main/sdks/ruby/CHANGELOG.md',

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mobiscroll-connect
 version: !ruby/object:Gem::Version
-  version: 1.5.1
+  version: 1.6.0
 platform: ruby
 authors:
 - Mobiscroll
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-22 00:00:00.000000000 Z
+date: 2026-10-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64
@@ -106,13 +106,14 @@ files:
 - lib/mobiscroll/connect/resources/events.rb
 - lib/mobiscroll/connect/resources/webhooks.rb
 - lib/mobiscroll/connect/version.rb
+- lib/mobiscroll/connect/webhook_verification.rb
 - mobiscroll-connect.gemspec
 homepage: https://mobiscroll.com/connect
 licenses:
 - MIT
 metadata:
   homepage_uri: https://mobiscroll.com/connect
-  source_code_uri: https://github.com/acidb/mobiscroll-connect-sdks
+  source_code_uri: https://github.com/acidb/mobiscroll-connect-sdks/tree/main/sdks/ruby
   documentation_uri: https://mobiscroll.com/docs/connect/ruby-sdk
   bug_tracker_uri: https://github.com/acidb/mobiscroll-connect-sdks/issues
   changelog_uri: https://github.com/acidb/mobiscroll-connect-sdks/blob/main/sdks/ruby/CHANGELOG.md