pago-sdk 1.0.0

data/lib/pago/v2026_04/webhooks.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Pago
+  module V2026_04
+    # Webhook verification and deserialization for the 2026-04 API.
+    #
+    # @example Rack / Rails
+    #   event = Pago::Webhooks.validate_event(
+    #     body: request.body.read,
+    #     headers: request.headers,
+    #     secret: ENV.fetch("PAGO_WEBHOOK_SECRET")
+    #   )
+    #   case event
+    #   when Pago::Models::WebhookOrderPaidPayload then fulfill(event.data)
+    #   end
+    module Webhooks
+      # @return [Hash{String => Class}] event type to payload model.
+      def self.event_types
+        @event_types ||= {
+          "benefit.created" => Models::WebhookBenefitCreatedPayload,
+          "benefit.updated" => Models::WebhookBenefitUpdatedPayload,
+          "benefit_grant.created" => Models::WebhookBenefitGrantCreatedPayload,
+          "benefit_grant.cycled" => Models::WebhookBenefitGrantCycledPayload,
+          "benefit_grant.revoked" => Models::WebhookBenefitGrantRevokedPayload,
+          "benefit_grant.updated" => Models::WebhookBenefitGrantUpdatedPayload,
+          "checkout.created" => Models::WebhookCheckoutCreatedPayload,
+          "checkout.expired" => Models::WebhookCheckoutExpiredPayload,
+          "checkout.updated" => Models::WebhookCheckoutUpdatedPayload,
+          "customer.created" => Models::WebhookCustomerCreatedPayload,
+          "customer.deleted" => Models::WebhookCustomerDeletedPayload,
+          "customer.state_changed" => Models::WebhookCustomerStateChangedPayload,
+          "customer.updated" => Models::WebhookCustomerUpdatedPayload,
+          "customer_seat.assigned" => Models::WebhookCustomerSeatAssignedPayload,
+          "customer_seat.claimed" => Models::WebhookCustomerSeatClaimedPayload,
+          "customer_seat.revoked" => Models::WebhookCustomerSeatRevokedPayload,
+          "member.created" => Models::WebhookMemberCreatedPayload,
+          "member.deleted" => Models::WebhookMemberDeletedPayload,
+          "member.updated" => Models::WebhookMemberUpdatedPayload,
+          "order.created" => Models::WebhookOrderCreatedPayload,
+          "order.paid" => Models::WebhookOrderPaidPayload,
+          "order.refunded" => Models::WebhookOrderRefundedPayload,
+          "order.updated" => Models::WebhookOrderUpdatedPayload,
+          "organization.updated" => Models::WebhookOrganizationUpdatedPayload,
+          "product.created" => Models::WebhookProductCreatedPayload,
+          "product.updated" => Models::WebhookProductUpdatedPayload,
+          "refund.created" => Models::WebhookRefundCreatedPayload,
+          "refund.updated" => Models::WebhookRefundUpdatedPayload,
+          "subscription.active" => Models::WebhookSubscriptionActivePayload,
+          "subscription.canceled" => Models::WebhookSubscriptionCanceledPayload,
+          "subscription.created" => Models::WebhookSubscriptionCreatedPayload,
+          "subscription.past_due" => Models::WebhookSubscriptionPastDuePayload,
+          "subscription.paused" => Models::WebhookSubscriptionPausedPayload,
+          "subscription.resumed" => Models::WebhookSubscriptionResumedPayload,
+          "subscription.revoked" => Models::WebhookSubscriptionRevokedPayload,
+          "subscription.uncanceled" => Models::WebhookSubscriptionUncanceledPayload,
+          "subscription.updated" => Models::WebhookSubscriptionUpdatedPayload
+        }.freeze
+      end
+
+      # @return [Array<String>] every event type known to this SDK version.
+      def self.known_event_types = event_types.keys
+
+      # Verify a raw webhook request and deserialize its payload.
+      #
+      # @param body [String] the raw request body, exactly as received.
+      # @param headers [Hash{String => String}] the request headers.
+      # @param secret [String] the endpoint secret, in `whsec_<base64>` form.
+      # @raise [Pago::WebhookSecretError] when the secret is not a valid secret.
+      # @raise [Pago::WebhookVerificationError] when the signature does not match.
+      # @raise [Pago::WebhookUnknownTypeError] when the event type is unknown.
+      # @raise [Pago::WebhookError] when the payload cannot be parsed.
+      # @return [Pago::Model] the deserialized event payload.
+      def self.validate_event(body:, headers:, secret:)
+        data = ::Pago::WebhookVerifier.verify(body: body, headers: headers, secret: secret)
+        event_type = data.is_a?(Hash) ? data["type"] : nil
+        payload_class = event_types[event_type]
+        raise ::Pago::WebhookUnknownTypeError, event_type if payload_class.nil?
+
+        payload = payload_class.from_json(data)
+        raise ::Pago::WebhookError, "Failed to parse webhook payload" if payload.nil?
+
+        payload
+      end
+    end
+  end
+end

data/lib/pago/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Pago
+  VERSION = "1.0.0"
+end

data/lib/pago/webhooks.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+module Pago
+  # Base error raised while processing a Pago webhook.
+  class WebhookError < Error; end
+
+  # Raised when a webhook signature cannot be verified.
+  class WebhookVerificationError < WebhookError; end
+
+  # Raised when the endpoint secret is not a Standard Webhooks secret.
+  #
+  # A secret is the `whsec_` prefix followed by the base64 encoding of the
+  # signing key. Anything else — a missing prefix, an empty or malformed
+  # base64 body — is a configuration mistake, so it is reported instead of
+  # being silently treated as a signature mismatch.
+  class WebhookSecretError < WebhookVerificationError
+    def initialize(reason = nil)
+      message = "Invalid webhook secret: expected the \"whsec_\" prefix followed by base64 encoded bytes"
+      super(reason.nil? ? message : "#{message} (#{reason})")
+    end
+  end
+
+  # Raised when a verified webhook type is unknown to this SDK version.
+  class WebhookUnknownTypeError < WebhookError
+    # @return [String, nil] the event type carried by the payload.
+    attr_reader :event_type
+
+    def initialize(event_type)
+      @event_type = event_type
+      super("Unknown webhook event type: #{event_type.inspect}")
+    end
+  end
+
+  # Signature verification for incoming webhooks.
+  #
+  # Implements the Standard Webhooks specification: the `webhook-id`,
+  # `webhook-timestamp` and `webhook-signature` headers are required, the
+  # timestamp must sit within a five minute window, and the signature is an
+  # HMAC-SHA256 of `id.timestamp.body` keyed with the *decoded* secret — the
+  # base64 body of `whsec_<base64>`, never the secret string itself. The
+  # header may carry several space separated `v1,<base64>` signatures — any
+  # match accepts the payload, which is what makes secret rotation possible.
+  module WebhookVerifier
+    TOLERANCE_SECONDS = 5 * 60
+    SIGNATURE_VERSION = "v1"
+    SECRET_PREFIX = "whsec_"
+
+    module_function
+
+    # Verify a raw webhook request and return its parsed payload.
+    #
+    # @param body [String] the raw request body, exactly as received.
+    # @param headers [Hash{String => String}] the request headers, case insensitive.
+    # @param secret [String] the endpoint secret, in `whsec_<base64>` form.
+    # @raise [Pago::WebhookSecretError] when the secret is not a valid secret.
+    # @raise [Pago::WebhookVerificationError] when the signature does not match.
+    # @raise [Pago::WebhookError] when the body is not valid JSON.
+    # @return [Hash] the parsed payload.
+    def verify(body:, headers:, secret:)
+      payload = normalize_body(body)
+      verify_signature(payload, headers, secret)
+      parse(payload)
+    end
+
+    def normalize_body(body)
+      payload = body.to_s.dup.force_encoding(Encoding::UTF_8)
+      raise WebhookError, "Failed to parse webhook payload" unless payload.valid_encoding?
+
+      payload
+    end
+
+    def parse(payload)
+      JSON.parse(payload)
+    rescue JSON::ParserError
+      raise WebhookError, "Failed to parse webhook payload"
+    end
+
+    def verify_signature(body, headers, secret)
+      key = derive_key(secret)
+
+      normalized = (headers || {}).each_with_object({}) do |(name, value), result|
+        result[name.to_s.downcase] = value
+      end
+      id = normalized["webhook-id"]
+      timestamp = normalized["webhook-timestamp"]
+      signature = normalized["webhook-signature"]
+      raise WebhookVerificationError, "Missing required headers" if blank?(id) || blank?(timestamp) || blank?(signature)
+
+      check_tolerance(parse_timestamp(timestamp))
+
+      expected = OpenSSL::HMAC.digest("SHA256", key, "#{id}.#{timestamp}.#{body}".b)
+      return if signature.to_s.split(" ").any? { |candidate| match?(candidate, expected) }
+
+      raise WebhookVerificationError, "No matching signature found"
+    end
+
+    # Derive the HMAC key from a Standard Webhooks secret: strip the `whsec_`
+    # prefix and base64 decode the rest.
+    #
+    # @param secret [String] the endpoint secret.
+    # @raise [Pago::WebhookSecretError] when the secret is empty, unprefixed or not base64.
+    # @return [String] the raw signing key.
+    def derive_key(secret)
+      value = secret.to_s
+      raise WebhookSecretError, "the secret is empty" if value.empty?
+      raise WebhookSecretError, "missing the \"#{SECRET_PREFIX}\" prefix" unless value.start_with?(SECRET_PREFIX)
+
+      encoded = value[SECRET_PREFIX.length..]
+      raise WebhookSecretError, "nothing follows the prefix" if encoded.nil? || encoded.empty?
+
+      key = decode_base64(encoded)
+      raise WebhookSecretError, "the part after the prefix is not valid base64" if key.nil? || key.empty?
+
+      key
+    end
+
+    def parse_timestamp(value)
+      Integer(value.to_s, 10)
+    rescue ArgumentError, TypeError
+      raise WebhookVerificationError, "Invalid signature headers"
+    end
+
+    def check_tolerance(seconds)
+      now = Time.now.to_i
+      raise WebhookVerificationError, "Message timestamp too old" if seconds < now - TOLERANCE_SECONDS
+      raise WebhookVerificationError, "Message timestamp too new" if seconds > now + TOLERANCE_SECONDS
+    end
+
+    def match?(candidate, expected)
+      version, separator, signature = candidate.partition(",")
+      return false unless separator == "," && version == SIGNATURE_VERSION
+
+      decoded = decode_base64(signature)
+      return false if decoded.nil?
+
+      secure_compare(expected, decoded)
+    end
+
+    # Compare two strings without leaking their contents through timing.
+    def secure_compare(left, right)
+      if OpenSSL.respond_to?(:secure_compare)
+        OpenSSL.secure_compare(left, right)
+      elsif defined?(Rack::Utils) && Rack::Utils.respond_to?(:secure_compare)
+        Rack::Utils.secure_compare(left, right)
+      else
+        left.bytesize == right.bytesize && OpenSSL.fixed_length_secure_compare(left, right)
+      end
+    end
+
+    # Strict base64 decoding: padding is required and stray characters are refused.
+    def decode_base64(value)
+      value.to_s.unpack1("m0")
+    rescue ArgumentError
+      nil
+    end
+
+    def blank?(value) = value.nil? || value.to_s.empty?
+  end
+end

data/lib/pago.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "openssl"
+require "uri"
+
+require_relative "pago/version"
+require_relative "pago/errors"
+require_relative "pago/serde"
+require_relative "pago/model"
+require_relative "pago/http"
+require_relative "pago/paginator"
+require_relative "pago/service"
+require_relative "pago/base_client"
+require_relative "pago/webhooks"
+require_relative "pago/v2026_04/enums"
+require_relative "pago/v2026_04/models"
+require_relative "pago/v2026_04/unions"
+require_relative "pago/v2026_04/errors"
+require_relative "pago/v2026_04/webhooks"
+require_relative "pago/v2026_04/client"
+
+# Pago — a billing platform for the intelligence era.
+#
+# The constants below alias the latest API version, so `Pago::Client` always
+# points at the newest generated client. Pin an explicit version module
+# (e.g. `Pago::V2026_04::Client`) to opt out of that.
+module Pago
+  # @return [Class] the client of the latest API version (2026-04).
+  Client = V2026_04::Client
+  Models = V2026_04::Models
+  Enums = V2026_04::Enums
+  Unions = V2026_04::Unions
+  Errors = V2026_04::Errors
+  Webhooks = V2026_04::Webhooks
+  Services = V2026_04::Services
+  LATEST_API_VERSION = "2026-04"
+end