qube_sync 0.2.2 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2c593eb9ef22a2ba0aea163fcbeb42d5bebb543d68df3f109df1e107e84daecf
-  data.tar.gz: 84ecbe1882466ad81c466384a226e091d1cef477fba15afa91932f852757bd04
+  metadata.gz: 6d91d913272b0ecdd7f2b2bf91b584e2ab2291841a3badf4641d67d385841b51
+  data.tar.gz: 00d4062eead7a747ddc51ee0eaf44f5e25799532028b3ed30343ec25f7e7843e
 SHA512:
-  metadata.gz: 92ec4c4a1ec346e26f99e38f7bfc8c5be77b01393a416b85f015a608cf4dd0dcdac0c916ce32b14a011ced23b1a0fe88f37a22db937428ea1d9a5514a55c30cb
-  data.tar.gz: 4a74b0a77a1c3e2193f722938a95cfbe8dfb4c2d06db06baecf0fb8bed7c9d7b18e10b06811424c2140635d033ea01db40057b2e18fa74ce448dfe2b5d13f8d2
+  metadata.gz: b244afce7cc38609ca0b100fb4f85102c13ca194d7d5cfd61d792950c37402cf84dd28e868830be11060bf5948482607ef206749c9b6c5b7f302da9df2883db6
+  data.tar.gz: 923cf67564f27f9be8a715ec059bdb4dfa70befc478eaeba7188bfe3a02c203b21b63d68e4db827c3d55727c4070c4c3d7f2c229f603dc75e109a7e6d9e7db8f

data/CHANGELOG.md

@@ -1,5 +1,50 @@
 ## [Unreleased]
 
+## [0.3.0] - 2026-10-23
+
+Adds `QubeSync::Webhooks`, which verifies a delivery and parses it into a typed event. Nothing
+existing changes: `verify_and_build_webhook!` works as it did in 0.2.4.
+
+- `QubeSync::Webhooks.verify(raw_body, header, secrets:, tolerance: 300, now: Time.now)` checks
+  the `X-QUBE-Signature` header and returns an event, or raises
+  `QubeSync::Webhooks::SignatureError` (a `QubeSync::Error`) whose `reason` is `:missing`,
+  `:malformed`, `:stale` or `:mismatch`. It takes the secret as an argument, one or a list while
+  a secret rotates, and never reads the environment. Its messages never hold the secret, a
+  signature or the body.
+- Passing a parsed body raises `TypeError`, and an empty list of secrets raises `ArgumentError`.
+  A body that verifies but isn't a JSON object raises `QubeSync::Webhooks::ParseError`.
+- `QubeSync::Webhooks.parse(raw_body)` (or `Event.from_json`) builds the event without
+  verifying.
+- One event class per type: `RequestEvent`, `WorkflowRunEvent`, `NotificationEvent`,
+  `ConnectionEvent`, `NameIndexEvent` and `UnknownEvent` (never refused). Each has `type`,
+  `event`, `timestamp`, `app_id`, `sandbox`, `dedupe_key`, `to_h` and `[]`; a missing key reads
+  as `nil`. Workflow runs and connections have `newer_than?(stored_revision)`. Notifications
+  don't, because they're never skipped by revision.
+- Specs run every case in `spec/fixtures/test_vectors.json`, generated by the QuBe Sync server.
+
+## [0.2.4] - 2026-10-22
+
+Security fixes for webhook verification. Upgrading needs no code change, but needs Ruby 3.3 or
+newer.
+
+- Requires Ruby 3.3 or newer (the oldest Ruby still supported) and Faraday 2.14.3 or newer, which
+  fixes GHSA-98m9-hrrm-r99r, GHSA-33mh-2634-fwr2 and GHSA-5rv5-xj5j-3484. 0.2.3 allowed Ruby 2.6
+  and any Faraday 2.
+
+- `verify_and_build_webhook!` verifies real deliveries: it signs `"<t>.<raw body>"` as the
+  server does and reads `t` and every `v1` from `X-QUBE-Signature` by key. 0.2.3 signed the body
+  alone and compared against the `v1=`-prefixed parts, so no real delivery verified.
+- Signatures are compared in constant time (`OpenSSL.fixed_length_secure_compare`), not with
+  `==`.
+- The timestamp must be within 300 seconds of now, either way. It was 500 seconds old, and any
+  timestamp in the future passed. `max_age` (seconds) still sets the window.
+- A missing or malformed header raises `InvalidWebhookSignatureError`, not `NoMethodError`.
+- The stale error says how old (or how far ahead) the timestamp was; it used to print
+  `#{max_age}ms` literally.
+- `RequestBuilder` sends `true` and `false` as the text `"true"` and `"false"`. 0.2.3 dropped
+  them, so `b.IsActive true` went out as an empty `<IsActive/>`.
+- Specs run against a delivery signed by the QuBe Sync server (`spec/fixtures/webhook_vectors.json`).
+
 ## [0.1.0] - 2025-01-31
 
 - Initial release

data/README.md

@@ -4,6 +4,8 @@ A simple wrapper around the QUBE Sync API.
 
 ## Installation
 
+Requires Ruby 3.3 or newer.
+
 Install the gem and add to the application's Gemfile by executing:
 
     $ bundle add qube_sync
@@ -118,10 +120,86 @@ QubeSync.verify_and_build_webhook!(request.body.read, request.headers['X-Qube-Si
 #   "<?xml version=\"1.0\" ?> <QBXML> <QBXMLMsgsRs> ... </QBXMLMsgsRs> </QBXML>" 
 # }
 
-# The default max age for a webhook is 500ms (0.5 seconds). You can change this by passing a max_age option:
-QubeSync.verify_and_build_webhook!(request.body.read, request.headers['X-Qube-Signature'], max_age: 1_000)
+# Pass the raw request body, before anything parses it. A bad or missing signature raises
+# QubeSync::InvalidWebhookSignatureError; answer 401.
+#
+# The timestamp must be within 300 seconds (5 minutes) of now, either way, or it raises
+# QubeSync::StaleWebhookError. max_age (in seconds) sets another window:
+QubeSync.verify_and_build_webhook!(request.body.read, request.headers['X-Qube-Signature'], max_age: 120)
+```
+
+## Webhooks
+
+`QubeSync::Webhooks` verifies a delivery's `X-QUBE-Signature` header and parses the body into a
+typed event. It doesn't need Rails or Rack, and never reads the environment: pass it the raw body,
+the header and your webhook secret.
+
+```ruby
+require "qube_sync"
+
+# raw_body: the request body exactly as received, before anything parses it.
+# header:   the X-QUBE-Signature header (nil when it's absent).
+def handle_qube_webhook(raw_body, header)
+  event = QubeSync::Webhooks.verify(raw_body, header, secrets: ENV.fetch("QUBE_WEBHOOK_SECRET"))
+
+  case event.type
+  when "request"
+    # A queued request's answer. Deduplicate on event.dedupe_key ("<page_request_id>:<state>").
+    # event.response_json, event.error, event.page, event.iteration_state
+  when "workflow_run"
+    # A run is waiting for an answer, or has ended. Skip it unless event.newer_than?(stored)
+    # for the revision stored with event.reference: deliveries can arrive out of order.
+    # event.awaiting_input? / completed? / failed? / cancelled?, event.prompt, event.output
+  when "notification"
+    # Data a running workflow sent. Deduplicate on event.dedupe_key (the delivery_id), and
+    # never skip one by revision. event.name, event.data
+  when "connection"
+    # Connected, setup cancelled, stalled or resumed. Deduplicate on event.dedupe_key, and skip
+    # it unless event.newer_than?(the revision stored for event.connection_id).
+  when "name_index"
+    # event.connection_id, event.name_index
+  else
+    # An event this version doesn't know yet: acknowledge it.
+  end
+
+  200
+rescue QubeSync::Webhooks::SignatureError => e
+  # e.reason is :missing, :malformed, :stale or :mismatch. The message is safe to log.
+  warn "QuBe Sync webhook refused: #{e.message}"
+  401
+end
+```
+
+- `secrets:` takes one secret or a list. While a secret rotates, a delivery carries one `v1`
+  signature per active secret, and either secret verifies it.
+- The timestamp must be within 300 seconds of now, either way. `tolerance:` (seconds) sets
+  another window, and `now:` (unix seconds or a `Time`) sets the clock, for tests.
+- Every event has `type`, `event`, `timestamp`, `app_id`, `sandbox`, `dedupe_key` and `to_h`
+  (the whole body). A missing key reads as `nil`, and `event["any_key"]` reads any other key.
+- `QubeSync::Webhooks.parse(raw_body)` builds the event without verifying it, for tests or for
+  code that verified the delivery elsewhere.
+
+In Rails, read the raw body with `request.raw_post`:
+
+```ruby
+class QubeWebhooksController < ActionController::API
+  def create
+    event = QubeSync::Webhooks.verify(
+      request.raw_post,
+      request.headers[QubeSync::Webhooks::HEADER],
+      secrets: Rails.application.credentials.qube_webhook_secret
+    )
+    QubeWebhookJob.perform_later(event.to_h) # route by type in the job, as above
+    head :ok
+  rescue QubeSync::Webhooks::SignatureError => e
+    Rails.logger.warn("QuBe Sync webhook refused: #{e.message}")
+    head :unauthorized
+  end
+end
 ```
 
+`QubeSync.verify_and_build_webhook!` (0.2.4) still works, and still returns the parsed Hash.
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
@@ -130,4 +208,4 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/qubeintegrations/qube_sync.
+Bug reports and pull requests are welcome on GitHub at https://github.com/qubeintegrations/qube_sync_rb.

data/lib/qube_sync/request_builder.rb

@@ -5,7 +5,7 @@ module QubeSync
     def initialize(version:, &block)
       @version = version
       @stack = []
-      instance_eval(&block) if block_given?
+      yield self if block_given?
     end
 
     def method_missing(tag_name, *args, &block)
@@ -16,12 +16,14 @@ module QubeSync
         "name" => tag_name.to_s,
       }
       element["attributes"] = attributes unless attributes.empty?
+      # qbXML's booleans are the words true and false.
+      text = text.to_s if text == true || text == false
       element["text"] = text if text.is_a?(String) || text.is_a?(Numeric)
 
       if block_given?
         element["children"] = []
         @stack.push(element)
-        instance_eval(&block)
+        block.call
         @stack.pop
       end
 

data/lib/qube_sync/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module QubeSync
-  VERSION = "0.2.2"
+  VERSION = "0.3.0"
 end

data/lib/qube_sync/webhooks/event.rb

@@ -0,0 +1,228 @@
+# frozen_string_literal: true
+
+module QubeSync
+  module Webhooks
+    # A parsed delivery. `QubeSync::Webhooks.parse` and `.verify` return one of the subclasses
+    # below, picked by the body: RequestEvent, WorkflowRunEvent, NotificationEvent,
+    # ConnectionEvent, NameIndexEvent, or UnknownEvent for anything else. Every accessor reads
+    # the body and returns nil for a missing key; `[]` reads any other key.
+    class Event
+      WORKFLOW_RUN_EVENTS = %w[
+        workflow_run.awaiting_input
+        workflow_run.completed
+        workflow_run.failed
+        workflow_run.cancelled
+      ].freeze
+      NOTIFICATION_EVENT = "workflow_run.notification"
+
+      # Picks the event class for a parsed body (a Hash with string keys).
+      def self.build(body)
+        event = body["event"]
+
+        klass =
+          if event.nil?
+            body["page_request_id"].nil? ? UnknownEvent : RequestEvent
+          elsif !event.is_a?(String)
+            UnknownEvent
+          elsif WORKFLOW_RUN_EVENTS.include?(event)
+            WorkflowRunEvent
+          elsif event == NOTIFICATION_EVENT
+            NotificationEvent
+          elsif event.start_with?("connection.")
+            ConnectionEvent
+          elsif event.start_with?("name_index.")
+            NameIndexEvent
+          else
+            UnknownEvent
+          end
+
+        klass.new(body)
+      end
+
+      # Parses a raw JSON body without verifying it. Same as `QubeSync::Webhooks.parse`.
+      def self.from_json(raw_body)
+        Webhooks.parse(raw_body)
+      end
+
+      def self.fields(*names)
+        names.each do |name|
+          key = name.to_s
+          define_method(name) { @body[key] }
+        end
+      end
+      private_class_method :fields
+
+      def initialize(body)
+        @body = body
+      end
+
+      fields :event, :timestamp, :app_id, :sandbox
+
+      # "request", "workflow_run", "notification", "connection", "name_index" or "unknown".
+      def type
+        self.class::TYPE
+      end
+
+      # The key to deduplicate deliveries on, or nil when this type has none.
+      def dedupe_key
+        nil
+      end
+
+      def reference
+        nil
+      end
+
+      def revision
+        nil
+      end
+
+      # Any key of the body, nil when it's missing.
+      def [](key)
+        @body[key.to_s]
+      end
+
+      def dig(*keys)
+        @body.dig(*keys.map { |key| key.is_a?(Symbol) ? key.to_s : key })
+      end
+
+      # The whole parsed body.
+      def to_h
+        @body
+      end
+
+      def ==(other)
+        other.instance_of?(self.class) && other.to_h == @body
+      end
+      alias eql? ==
+
+      def hash
+        [self.class, @body].hash
+      end
+
+      def inspect
+        "#<#{self.class.name} type=#{type.inspect} event=#{event.inspect}>"
+      end
+
+      # Shared by the types that carry a revision to compare against the stored one.
+      module Revisioned
+        def revision
+          @body["revision"]
+        end
+
+        # True when this delivery is newer than the revision stored for its subject (or nothing is
+        # stored yet). Skip the delivery when false: an older one arrived late.
+        def newer_than?(stored_revision)
+          return true if stored_revision.nil?
+          return false if revision.nil?
+
+          revision > stored_revision
+        end
+      end
+    end
+
+    # A queued request's answer (or error). Deduplicate on `dedupe_key`, page_request_id + state.
+    class RequestEvent < Event
+      TYPE = "request"
+
+      fields :id, :page_request_id, :state, :page, :iteration_state, :response_json, :error
+
+      def dedupe_key
+        "#{page_request_id}:#{state}"
+      end
+    end
+
+    # A workflow run that is waiting for an answer, or has ended. Store by `reference` and skip
+    # it unless `newer_than?` the revision you stored.
+    class WorkflowRunEvent < Event
+      include Event::Revisioned
+
+      TYPE = "workflow_run"
+
+      fields :run_id, :reference, :run_state, :workflow, :connection_id, :prompt, :outcome, :output,
+             :error, :summary, :cancel_reason, :links
+
+      def awaiting_input?
+        event == "workflow_run.awaiting_input"
+      end
+
+      def completed?
+        event == "workflow_run.completed"
+      end
+
+      def failed?
+        event == "workflow_run.failed"
+      end
+
+      def cancelled?
+        event == "workflow_run.cancelled"
+      end
+    end
+
+    # Data a running workflow sent along. Deduplicate on `delivery_id`; never skip one by revision.
+    class NotificationEvent < Event
+      TYPE = "notification"
+
+      fields :run_id, :reference, :revision, :delivery_id, :seq, :name, :state, :from, :data
+
+      def dedupe_key
+        delivery_id
+      end
+    end
+
+    # A connection was set up, cancelled, stalled or resumed. Deduplicate on `delivery_id`, and
+    # skip it unless `newer_than?` the connection's stored revision.
+    class ConnectionEvent < Event
+      include Event::Revisioned
+
+      TYPE = "connection"
+
+      fields :delivery_id, :connection
+
+      def connection_id
+        connection_hash["id"]
+      end
+
+      def stall_reason
+        connection_hash["stall_reason"]
+      end
+
+      def dedupe_key
+        delivery_id
+      end
+
+      def connected?
+        event == "connection.connected"
+      end
+
+      def setup_cancelled?
+        event == "connection.setup_cancelled"
+      end
+
+      def stalled?
+        event == "connection.stalled"
+      end
+
+      def resumed?
+        event == "connection.resumed"
+      end
+
+      private
+
+      def connection_hash
+        connection.is_a?(Hash) ? connection : {}
+      end
+    end
+
+    # A connection's name index finished building, or failed.
+    class NameIndexEvent < Event
+      TYPE = "name_index"
+
+      fields :connection_id, :name_index
+    end
+
+    # Anything this version of the library doesn't know. Never refused: acknowledge it (or log it).
+    class UnknownEvent < Event
+      TYPE = "unknown"
+    end
+  end
+end

data/lib/qube_sync/webhooks.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+require "json"
+require "openssl"
+
+module QubeSync
+  class Error < StandardError; end
+
+  # Verifies QuBe Sync webhook deliveries and parses them into typed events.
+  #
+  #   event = QubeSync::Webhooks.verify(raw_body, header, secrets: ENV.fetch("QUBE_WEBHOOK_SECRET"))
+  #
+  # Framework-free: it never reads the environment or a request object. Pass the raw request body
+  # as received and the value of the `X-QUBE-Signature` header.
+  module Webhooks
+    # The header that carries the signature, and its name in a Rack env.
+    HEADER = "X-QUBE-Signature"
+    RACK_HEADER = "HTTP_X_QUBE_SIGNATURE"
+
+    # Seconds a delivery's timestamp may be from now, either way.
+    DEFAULT_TOLERANCE = 300
+
+    REASONS = %i[missing malformed stale mismatch].freeze
+
+    # A delivery that failed verification. Answer it with 401. `reason` is one of
+    # `:missing`, `:malformed`, `:stale`, `:mismatch`. The message is safe to log: it never holds
+    # a secret, a signature or the body.
+    class SignatureError < QubeSync::Error
+      attr_reader :reason
+
+      def initialize(reason, message = nil)
+        @reason = reason
+        super(message || default_message(reason))
+      end
+
+      private
+
+      def default_message(reason)
+        case reason
+        when :missing then "No #{HEADER} header"
+        when :malformed then "Malformed #{HEADER} header: expected t=<unix seconds>,v1=<hex>"
+        when :stale then "Webhook timestamp is outside the tolerance"
+        when :mismatch then "Webhook signature doesn't match any of the given secrets"
+        else "Webhook signature is invalid (#{reason})"
+        end
+      end
+    end
+
+    # A body that verified (or was handed to `parse`) but isn't a JSON object.
+    class ParseError < QubeSync::Error; end
+
+    module_function
+
+    # Verifies a delivery and returns its typed event (see `parse`). Raises SignatureError when
+    # the header is missing, malformed, stale or matches none of `secrets`.
+    #
+    # - `raw_body`: the request body as received (a String), before anything parses it.
+    # - `header`: the `X-QUBE-Signature` value (nil when absent).
+    # - `secrets:`: the app's webhook secret, or a list of them while one rotates.
+    # - `tolerance:`: seconds the timestamp may be from `now`, either way.
+    # - `now:`: unix seconds, or a Time.
+    def verify(raw_body, header, secrets:, tolerance: DEFAULT_TOLERANCE, now: Time.now)
+      raw_body = raw_body!(raw_body)
+      secrets = secrets!(secrets)
+      now = unix_seconds!(now)
+
+      header = header.to_s.b.strip
+      raise SignatureError.new(:missing) if header.empty?
+
+      timestamp, signatures = parse_header(header)
+
+      age = now - timestamp.to_i
+      if age.abs > tolerance
+        when_sent = age.positive? ? "#{age} seconds old" : "#{-age} seconds in the future"
+        raise SignatureError.new(
+          :stale,
+          "Webhook timestamp is #{when_sent}; it must be within #{tolerance} seconds of now. Check this server's clock."
+        )
+      end
+
+      signed = "#{timestamp}.".b + raw_body.b
+      expected = secrets.map { |secret| OpenSSL::HMAC.hexdigest("sha256", secret, signed) }
+      matched = expected.product(signatures).any? { |exp, sig| secure_compare(exp, sig) }
+      raise SignatureError.new(:mismatch) unless matched
+
+      parse(raw_body)
+    end
+
+    # Builds the typed event from a raw body without verifying it: for tests, and for code that
+    # verified the delivery elsewhere.
+    def parse(raw_body)
+      raw_body = raw_body!(raw_body)
+      text = raw_body.encoding == Encoding::UTF_8 ? raw_body : raw_body.dup.force_encoding(Encoding::UTF_8)
+
+      body =
+        begin
+          JSON.parse(text)
+        rescue JSON::ParserError, EncodingError
+          raise ParseError, "Webhook body isn't valid JSON"
+        end
+      raise ParseError, "Webhook body isn't a JSON object" unless body.is_a?(Hash)
+
+      Event.build(body)
+    end
+
+    # Splits the header into its `t` and its non-empty `v1`s, or raises :malformed.
+    def parse_header(header)
+      timestamp = nil
+      signatures = []
+
+      header.split(",").each do |part|
+        key, value = part.strip.split("=", 2)
+        next if value.nil?
+
+        case key
+        when "t" then timestamp ||= value
+        when "v1" then signatures << value unless value.empty?
+        end
+      end
+
+      unless timestamp&.match?(/\A[0-9]+\z/) && !signatures.empty?
+        raise SignatureError.new(:malformed)
+      end
+
+      [timestamp, signatures]
+    end
+
+    # Constant-time comparison of two byte strings; different lengths are simply false.
+    def secure_compare(a, b)
+      a = a.b
+      b = b.b
+      return false unless a.bytesize == b.bytesize
+
+      OpenSSL.fixed_length_secure_compare(a, b)
+    end
+
+    def raw_body!(raw_body)
+      return raw_body if raw_body.is_a?(String)
+
+      raise TypeError,
+            "Pass the raw request body as a String (in Rails, request.raw_post), not a #{raw_body.class}: " \
+            "the signature covers the exact bytes QuBe Sync sent"
+    end
+
+    def secrets!(secrets)
+      list = secrets.is_a?(String) ? [secrets] : Array(secrets)
+      raise ArgumentError, "secrets is empty: pass the app's webhook secret" if list.empty?
+      unless list.all? { |secret| secret.is_a?(String) && !secret.empty? }
+        raise ArgumentError, "each secret must be a non-empty String"
+      end
+
+      list
+    end
+
+    def unix_seconds!(now)
+      case now
+      when Integer then now
+      when Time then now.to_i
+      when Numeric then now.floor
+      else
+        return now.to_time.to_i if now.respond_to?(:to_time)
+
+        raise ArgumentError, "now must be unix seconds or a Time, not a #{now.class}"
+      end
+    end
+
+    private_class_method :parse_header, :secure_compare, :raw_body!, :secrets!, :unix_seconds!
+  end
+end
+
+require_relative "webhooks/event"

data/lib/qube_sync.rb

@@ -1,6 +1,9 @@
 require_relative "qube_sync/version"
 require_relative "qube_sync/request_builder"
+require_relative "qube_sync/webhooks"
 require "faraday"
+require "json"
+require "openssl"
 
 module QubeSync
   class Error < StandardError; end
@@ -85,6 +88,13 @@ module QubeSync
     def get_connection(connection_id)
       get("connections/#{connection_id}").fetch("data")
     end
+
+    def valid_connection?(connection_id)
+      get_connection(connection_id)
+      true
+    rescue Error => e
+      false
+    end
   
     def queue_request(connection_id, request)
       url = "connections/#{connection_id}/queued_requests"
@@ -121,12 +131,26 @@ module QubeSync
     end
   
   
+    # Parses an `X-QUBE-Signature` header, `t=<unix seconds>,v1=<hex>[,v1=<hex>]`,
+    # by key. There is one `v1` per active webhook secret while a secret rotates.
     def extract_signature_meta(header)
-      parts = header.split(',')
-      ts = parts.first
-      signatures = parts[1..-1]
+      timestamp = nil
+      signatures = []
+
+      header.to_s.split(",").each do |part|
+        key, value = part.strip.split("=", 2)
+        case key
+        when "t" then timestamp = value
+        when "v1" then signatures << value if value && !value.empty?
+        end
+      end
+
+      unless timestamp && timestamp.match?(/\A\d+\z/)
+        raise InvalidWebhookSignatureError.new("Invalid X-QUBE-Signature header: no t=<unix seconds>")
+      end
+
       {
-        timestamp: ts.split("=").last.to_i,
+        timestamp: timestamp.to_i,
         signatures: signatures
       }
     end
@@ -155,18 +179,30 @@ module QubeSync
       OpenSSL::HMAC.hexdigest('sha256', api_secret, payload)
     end
   
-    def verify_and_build_webhook!(body, signature, max_age: 500)
+    # Verifies a webhook against its `X-QUBE-Signature` header and returns the
+    # parsed body. `body` must be the raw request body, unparsed. The timestamp
+    # must be within `max_age` seconds of now, either way.
+    def verify_and_build_webhook!(body, signature, max_age: 300)
       meta = extract_signature_meta(signature)
-  
-      if meta[:timestamp] < Time.now.to_i - max_age
-        raise StaleWebhookError.new('Timestamp more than #{max_age}ms old. To increase this, pass a different value for max_age.')
+
+      age = Time.now.to_i - meta[:timestamp]
+      if age.abs > max_age
+        when_sent = age.positive? ? "#{age} seconds old" : "#{-age} seconds in the future"
+        raise StaleWebhookError.new("Webhook timestamp is #{when_sent}; it must be within #{max_age} seconds of now. Check this server's clock.")
       end
-      
-      if meta[:signatures].detect { |sig| sign_payload(body) == sig }
+
+      expected = sign_payload("#{meta[:timestamp]}.#{body}")
+      if meta[:signatures].any? { |sig| secure_compare(expected, sig) }
         JSON.parse(body)
       else
         raise InvalidWebhookSignatureError.new("Webhook signature mismatch")
       end
-  
+    end
+
+    # Constant-time string comparison, so a mismatch takes as long wherever it is.
+    def secure_compare(a, b)
+      return false unless a.bytesize == b.bytesize
+
+      OpenSSL.fixed_length_secure_compare(a, b)
     end
 end

data/qube_sync.gemspec

@@ -15,7 +15,7 @@ Gem::Specification.new do |spec|
   Manage connections, queued requests, and more with the QUBE Sync API.
   """
   spec.homepage = "https://github.com/qubeintegrations/qube_sync_rb"
-  spec.required_ruby_version = ">= 2.6.0"
+  spec.required_ruby_version = ">= 3.3.0"
 
   # spec.metadata["allowed_push_host"] = "TODO: Set to your gem server 'https://example.com'"
 
@@ -36,7 +36,7 @@ Gem::Specification.new do |spec|
   spec.require_paths = ["lib"]
 
   # Uncomment to register a new dependency of your gem
-  spec.add_dependency "faraday", "~> 2.0"
+  spec.add_dependency "faraday", "~> 2.14", ">= 2.14.3"
 
 
   # For more information and examples about making a new gem, check out our

metadata

@@ -1,13 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: qube_sync
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.3.0
 platform: ruby
 authors:
 - Garrett Lancaster
+autorequire:
 bindir: exe
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2026-10-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -15,14 +16,20 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: '2.14'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.14.3
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: '2.14'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.14.3
 description: "\n  Easily create and manage QUBE Sync API resources in Ruby.\n\n  Manage
   connections, queued requests, and more with the QUBE Sync API.\n  "
 email:
@@ -39,6 +46,8 @@ files:
 - lib/qube_sync.rb
 - lib/qube_sync/request_builder.rb
 - lib/qube_sync/version.rb
+- lib/qube_sync/webhooks.rb
+- lib/qube_sync/webhooks/event.rb
 - qube_sync.gemspec
 - sig/qube_sync.rbs
 homepage: https://github.com/qubeintegrations/qube_sync_rb
@@ -47,6 +56,7 @@ metadata:
   homepage_uri: https://github.com/qubeintegrations/qube_sync_rb
   source_code_uri: https://github.com/qubeintegrations/qube_sync_rb
   changelog_uri: https://github.com/qubeintegrations/qube_sync_rb/blob/main/CHANGELOG.md
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -54,14 +64,15 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.6.0
+      version: 3.3.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 3.5.22
+signing_key:
 specification_version: 4
 summary: Ruby library for the QUBE Sync API
 test_files: []