vortex-ruby-sdk 1.8.4 → 1.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 677efb240644fe95c61d07a325952a6d2f8c6851eb14d59d17178d2c74881629
-  data.tar.gz: 83ad91fa108419346c2b6a707b62316573fdc5137d213a141840a599eca02dbe
+  metadata.gz: b8665551bcdf4cf5b7ab05fc5b2dd880b9e1166dd4f544acceb864365e86c8db
+  data.tar.gz: 82d89462684d03e6b26769f20b8a44ba3f4fe71cf729ce78f54268f070fa36df
 SHA512:
-  metadata.gz: 324e85fc0660f7b952932a163ad10df4ae17f8f81dafd7c8eb6d8de70e771146474c0cc147d7643ae689f9629eafba0b9884c6f022b3091fb4147a3a1dc2f1eb
-  data.tar.gz: 2d780b17c5697ffcb0532bfcabce7756bd80a672b74417b5194e0c3e9089de31c0bc8c03977b4a0fdce0e416af1bb2a85868b2aa6050d2bf6a9fe9fbf7aa45e5
+  metadata.gz: 32a6d0a546f91c5165f43af6ac0ed995386b92d267006eb6793b865676fe0bcfe6631e748294ecf589253d7621df492aff7b442881266f7906dc6833b78be63e
+  data.tar.gz: 39253da9f792aacc194e619eb4ab00104d15ce7901ca5345a82e1681f3aa2d0e0bb268c6b832fad3537736641378f57fe3ee2ae31a5af8b2157ea5a8a2b02c17

data/README.md

@@ -262,6 +262,50 @@ To install this gem onto your local machine, run `bundle exec rake install`.
 
 ## Contributing
 
+## Webhooks
+
+The SDK provides built-in support for verifying and parsing incoming webhook events from Vortex.
+
+```ruby
+require 'vortex'
+
+webhooks = Vortex::Webhooks.new(secret: ENV['VORTEX_WEBHOOK_SECRET'])
+
+# In your HTTP handler (Rails example):
+class WebhooksController < ApplicationController
+  skip_before_action :verify_authenticity_token
+
+  def create
+    payload = request.body.read
+    signature = request.headers['X-Vortex-Signature']
+
+    begin
+      event = webhooks.construct_event(payload, signature)
+    rescue Vortex::WebhookSignatureError
+      head :bad_request
+      return
+    end
+
+    case event
+    when Vortex::WebhookEvent
+      Rails.logger.info "Webhook event: #{event.type}"
+    when Vortex::AnalyticsEvent
+      Rails.logger.info "Analytics event: #{event.name}"
+    end
+
+    head :ok
+  end
+end
+```
+
+### Event Type Constants
+
+```ruby
+if event.type == Vortex::WebhookEventTypes::INVITATION_ACCEPTED
+  # Handle invitation accepted
+end
+```
+
 Bug reports and pull requests are welcome on GitHub at https://github.com/vortexsoftware/vortex-ruby-sdk.
 
 ## License

data/lib/vortex/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Vortex
-  VERSION = '1.8.4'
+  VERSION = '1.9.0'
 end

data/lib/vortex/webhook_types.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module Vortex
+  # Webhook event type constants
+  module WebhookEventTypes
+    # Invitation Lifecycle
+    INVITATION_CREATED = 'invitation.created'
+    INVITATION_ACCEPTED = 'invitation.accepted'
+    INVITATION_DEACTIVATED = 'invitation.deactivated'
+    INVITATION_EMAIL_DELIVERED = 'invitation.email.delivered'
+    INVITATION_EMAIL_BOUNCED = 'invitation.email.bounced'
+    INVITATION_EMAIL_OPENED = 'invitation.email.opened'
+    INVITATION_LINK_CLICKED = 'invitation.link.clicked'
+    INVITATION_REMINDER_SENT = 'invitation.reminder.sent'
+
+    # Deployment Lifecycle
+    DEPLOYMENT_CREATED = 'deployment.created'
+    DEPLOYMENT_DEACTIVATED = 'deployment.deactivated'
+
+    # A/B Testing
+    ABTEST_STARTED = 'abtest.started'
+    ABTEST_WINNER_DECLARED = 'abtest.winner_declared'
+
+    # Member/Group
+    MEMBER_CREATED = 'member.created'
+    GROUP_MEMBER_ADDED = 'group.member.added'
+
+    # Email
+    EMAIL_COMPLAINED = 'email.complained'
+
+    ALL = [
+      INVITATION_CREATED, INVITATION_ACCEPTED, INVITATION_DEACTIVATED,
+      INVITATION_EMAIL_DELIVERED, INVITATION_EMAIL_BOUNCED, INVITATION_EMAIL_OPENED,
+      INVITATION_LINK_CLICKED, INVITATION_REMINDER_SENT,
+      DEPLOYMENT_CREATED, DEPLOYMENT_DEACTIVATED,
+      ABTEST_STARTED, ABTEST_WINNER_DECLARED,
+      MEMBER_CREATED, GROUP_MEMBER_ADDED,
+      EMAIL_COMPLAINED
+    ].freeze
+  end
+
+  # Analytics event type constants
+  module AnalyticsEventTypes
+    WIDGET_LOADED = 'widget_loaded'
+    INVITATION_SENT = 'invitation_sent'
+    INVITATION_CLICKED = 'invitation_clicked'
+    INVITATION_ACCEPTED = 'invitation_accepted'
+    SHARE_TRIGGERED = 'share_triggered'
+  end
+
+  # A Vortex webhook event representing a server-side state change
+  #
+  # @attr_reader id [String] Unique event ID
+  # @attr_reader type [String] The semantic event type
+  # @attr_reader timestamp [String] ISO-8601 timestamp
+  # @attr_reader account_id [String] The account ID
+  # @attr_reader environment_id [String, nil] The environment ID
+  # @attr_reader source_table [String] The source table
+  # @attr_reader operation [String] The database operation
+  # @attr_reader data [Hash] Event-specific payload data
+  class WebhookEvent
+    attr_reader :id, :type, :timestamp, :account_id, :environment_id,
+                :source_table, :operation, :data
+
+    def initialize(attrs)
+      @id = attrs['id']
+      @type = attrs['type']
+      @timestamp = attrs['timestamp']
+      @account_id = attrs['accountId']
+      @environment_id = attrs['environmentId']
+      @source_table = attrs['sourceTable']
+      @operation = attrs['operation']
+      @data = attrs['data'] || {}
+    end
+  end
+
+  # An analytics event representing client-side behavioral telemetry
+  class AnalyticsEvent
+    attr_reader :id, :name, :account_id, :organization_id, :project_id,
+                :environment_id, :deployment_id, :widget_configuration_id,
+                :foreign_user_id, :session_id, :payload, :platform,
+                :segmentation, :timestamp
+
+    def initialize(attrs)
+      @id = attrs['id']
+      @name = attrs['name']
+      @account_id = attrs['accountId']
+      @organization_id = attrs['organizationId']
+      @project_id = attrs['projectId']
+      @environment_id = attrs['environmentId']
+      @deployment_id = attrs['deploymentId']
+      @widget_configuration_id = attrs['widgetConfigurationId']
+      @foreign_user_id = attrs['foreignUserId']
+      @session_id = attrs['sessionId']
+      @payload = attrs['payload']
+      @platform = attrs['platform']
+      @segmentation = attrs['segmentation']
+      @timestamp = attrs['timestamp']
+    end
+  end
+
+  # Returns true if the parsed hash is a webhook event
+  def self.webhook_event?(parsed)
+    parsed.key?('type') && !parsed.key?('name')
+  end
+
+  # Returns true if the parsed hash is an analytics event
+  def self.analytics_event?(parsed)
+    parsed.key?('name')
+  end
+end

data/lib/vortex/webhooks.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require 'openssl'
+require 'json'
+
+module Vortex
+  # Error raised when webhook signature verification fails
+  class WebhookSignatureError < VortexError
+    def initialize(message = nil)
+      super(message || 'Webhook signature verification failed. Ensure you are using the raw request body and the correct signing secret.')
+    end
+  end
+
+  # Core webhook verification and parsing.
+  #
+  # This class is framework-agnostic — use it directly or with
+  # the Rails/Sinatra framework integrations.
+  #
+  # @example
+  #   webhooks = Vortex::Webhooks.new(secret: ENV['VORTEX_WEBHOOK_SECRET'])
+  #   event = webhooks.construct_event(request.body.read, request.env['HTTP_X_VORTEX_SIGNATURE'])
+  class Webhooks
+    # @param secret [String] The webhook signing secret from your Vortex dashboard
+    def initialize(secret:)
+      raise ArgumentError, 'Vortex::Webhooks requires a secret' if secret.nil? || secret.empty?
+
+      @secret = secret
+    end
+
+    # Verify the HMAC-SHA256 signature of an incoming webhook payload.
+    #
+    # @param payload [String] The raw request body
+    # @param signature [String] The value of the X-Vortex-Signature header
+    # @return [Boolean] true if the signature is valid
+    def verify_signature(payload, signature)
+      return false if signature.nil? || signature.empty?
+
+      expected = OpenSSL::HMAC.hexdigest('SHA256', @secret, payload)
+
+      # Timing-safe comparison to prevent timing attacks
+      secure_compare(signature, expected)
+    end
+
+    # Verify and parse an incoming webhook payload.
+    #
+    # @param payload [String] The raw request body
+    # @param signature [String] The value of the X-Vortex-Signature header
+    # @return [WebhookEvent, AnalyticsEvent] A typed event object
+    # @raise [WebhookSignatureError] If the signature is invalid
+    def construct_event(payload, signature)
+      raise WebhookSignatureError unless verify_signature(payload, signature)
+
+      parsed = JSON.parse(payload)
+
+      if Vortex.webhook_event?(parsed)
+        WebhookEvent.new(parsed)
+      elsif Vortex.analytics_event?(parsed)
+        AnalyticsEvent.new(parsed)
+      else
+        WebhookEvent.new(parsed)
+      end
+    end
+
+    private
+
+    # Timing-safe string comparison
+    def secure_compare(a, b)
+      return false unless a.bytesize == b.bytesize
+
+      OpenSSL.fixed_length_secure_compare(a, b)
+    rescue StandardError
+      false
+    end
+  end
+end

data/lib/vortex.rb

@@ -3,6 +3,8 @@
 require 'vortex/version'
 require 'vortex/error'
 require 'vortex/types'
+require 'vortex/webhook_types'
+require 'vortex/webhooks'
 require 'vortex/client'
 
 # Vortex Ruby SDK

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: vortex-ruby-sdk
 version: !ruby/object:Gem::Version
-  version: 1.8.4
+  version: 1.9.0
 platform: ruby
 authors:
 - Vortex Software
@@ -160,6 +160,8 @@ files:
 - lib/vortex/sinatra.rb
 - lib/vortex/types.rb
 - lib/vortex/version.rb
+- lib/vortex/webhook_types.rb
+- lib/vortex/webhooks.rb
 - vortex-ruby-sdk.gemspec
 homepage: https://github.com/vortexsoftware/vortex-ruby-sdk
 licenses: