signwell_sdk 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a977e911e6115277298236df5ce9a715dacb3cf8986d387c718a31db5138566a
-  data.tar.gz: 1e8c8cc0051656d1ebafd9489d7564508683784d3ffb8dd6572e54c356610bc0
+  metadata.gz: 55bbaffc014507a2d8aac8a98b5050e8283576e119595023bcdc80de464a3d10
+  data.tar.gz: 2f3338dfec89e4806bffa9fc1bf5ad5004c72e5fff5b6b99dd843cdaac38d139
 SHA512:
-  metadata.gz: 1f9f4838d88deebd9c7647ed1eaf6ff06892bfd00fbd1f16de2fb0aacc9e0ff07e26db4b21aeb8e631f3f8f771a2a6afc42152570e303bec9b1608e5ddbf88c6
-  data.tar.gz: 3a5b9325c09517a14ea25680a5b9f4afc2d54f9362c8e9f0538258364cc896101bd6df8b9cc3a9bafe4d9d09e30a10d8abef89cd39893edfb27ab9564036fe52
+  metadata.gz: 67288c6373cb34e4f1ac755f5b2ceb94468aabb32112a7637407c759c6dc1088d35b8d6cce81884ab3d244328822fad089828a321f13d40001a7efbf05fc3d7d
+  data.tar.gz: 58db67c107fade9f556042632aea5a3b22c39ff94ce811bd1293fbfc2469c36cf293d84b377236fe5f435eccbfb5f24ccfcd5c4ded112f09dd2a8e55fa1830aa

data/examples/09_webhook_validation.rb

@@ -3,9 +3,14 @@
 # Webhook Signature Validation
 #
 # When SignWell sends a webhook to your endpoint, each payload includes
-# a `hash` field with an HMAC-SHA256 signature. Use SignWell::Webhook.verify_event
+# an `event.hash` field with an HMAC-SHA256 signature. Use SignWell::Webhook.verify_event
 # to validate the signature before processing the event.
 #
+# The webhook payload has this structure:
+#   { "event": { "type": "...", "time": ..., "hash": "..." }, "data": { ... } }
+#
+# You must pass `payload['event']` (not the full payload) to verify_event.
+#
 # Your webhook ID is available in the SignWell dashboard (Settings > Webhooks).
 
 require 'signwell_sdk'
@@ -13,7 +18,8 @@ require 'sinatra'
 require 'json'
 
 post '/webhooks/signwell' do
-  event = JSON.parse(request.body.read)
+  payload = JSON.parse(request.body.read)
+  event = payload['event']
 
   unless SignWell::Webhook.verify_event(event: event, webhook_id: ENV['SIGNWELL_WEBHOOK_ID'])
     halt 401, 'Invalid signature'
@@ -21,9 +27,9 @@ post '/webhooks/signwell' do
 
   case event['type']
   when 'document_completed'
-    puts "Document #{event.dig('data', 'id')} completed"
+    puts "Document #{payload.dig('data', 'id')} completed"
   when 'document_declined'
-    puts "Document #{event.dig('data', 'id')} declined"
+    puts "Document #{payload.dig('data', 'id')} declined"
   end
 
   status 200

data/lib/signwell_sdk/version.rb

@@ -11,5 +11,5 @@ Generator version: 7.12.0
 =end
 
 module SignWell
-  VERSION = '0.1.0'
+  VERSION = '0.1.1'
 end

data/lib/signwell_sdk/webhook.rb

@@ -10,17 +10,15 @@ module SignWell
   # computed from the event type and timestamp, using your webhook's secret ID
   # as the key.
   #
-  # @example Verify a webhook in a Rails controller
+  # @example Verify a webhook in a Rails controller (using verify_event!)
   #   class WebhooksController < ApplicationController
   #     skip_before_action :verify_authenticity_token
   #
   #     def create
-  #       event = JSON.parse(request.body.read)
+  #       payload = JSON.parse(request.body.read)
+  #       event = payload['event']
   #
-  #       unless SignWell::Webhook.verify_event(event: event, webhook_id: ENV['SIGNWELL_WEBHOOK_ID'])
-  #         head :unauthorized
-  #         return
-  #       end
+  #       SignWell::Webhook.verify_event!(event: event, webhook_id: ENV['SIGNWELL_WEBHOOK_ID'])
   #
   #       # Process the verified event
   #       case event['type']
@@ -29,12 +27,15 @@ module SignWell
   #       end
   #
   #       head :ok
+  #     rescue ArgumentError
+  #       head :unauthorized
   #     end
   #   end
   #
-  # @example Verify a webhook in a Sinatra app
+  # @example Verify a webhook in a Sinatra app (using verify_event)
   #   post '/webhooks/signwell' do
-  #     event = JSON.parse(request.body.read)
+  #     payload = JSON.parse(request.body.read)
+  #     event = payload['event']
   #
   #     halt 401 unless SignWell::Webhook.verify_event(event: event, webhook_id: ENV['SIGNWELL_WEBHOOK_ID'])
   #
@@ -45,23 +46,56 @@ module SignWell
   # @see https://developers.signwell.com/reference/webhooks SignWell Webhooks Documentation
   module Webhook
     # Verifies the authenticity of a SignWell webhook event using HMAC-SHA256.
+    # Returns +false+ for missing or invalid arguments instead of raising.
+    #
+    # @param event [Hash] The +event+ object from the webhook payload.
+    #   Must contain +'type'+, +'time'+, and +'hash'+ keys.
+    # @param webhook_id [String] Your webhook's secret ID.
+    # @return [Boolean] +true+ if the signature is valid, +false+ otherwise
+    # @see #verify_event! Bang version that raises on invalid input
+    def self.verify_event(event:, webhook_id:)
+      verify_event!(event: event, webhook_id: webhook_id)
+    rescue ArgumentError
+      false
+    end
+
+    # Verifies the authenticity of a SignWell webhook event using HMAC-SHA256.
+    # Raises +ArgumentError+ with a descriptive message when input is invalid.
     #
     # Computes +HMAC-SHA256(webhook_id, "type@time")+ and compares it to the
     # +hash+ field in the event payload using a constant-time comparison.
     #
-    # @param event [Hash] Parsed webhook JSON payload. Must contain:
+    # @param event [Hash] The +event+ object from the webhook payload.
+    #   Must contain:
     #   - +'type'+ (String) - the event type, e.g. +"document_completed"+
-    #   - +'time'+ (String) - ISO 8601 timestamp of the event
+    #   - +'time'+ (String, Integer) - timestamp of the event
     #   - +'hash'+ (String) - HMAC-SHA256 hex digest to verify against
     # @param webhook_id [String] Your webhook's secret ID (found in your
     #   SignWell dashboard under API > Webhooks). Used as the HMAC key.
     # @return [Boolean] +true+ if the signature is valid, +false+ otherwise
-    # @raise [NoMethodError] if +event+ is missing required keys
-    def self.verify_event(event:, webhook_id:)
-      data = "#{event['type']}@#{event['time']}"
-      expected = event['hash']
+    # @raise [ArgumentError] if +webhook_id+ is missing or +event+ is missing
+    #   required keys
+    def self.verify_event!(event:, webhook_id:)
+      raise ArgumentError, 'webhook_id must be a non-empty string' unless webhook_id.is_a?(String) && !webhook_id.empty?
+      raise ArgumentError, 'event must be a Hash' unless event.is_a?(Hash)
+
+      type = event['type']
+      time = event['time']
+      hash = event['hash']
+
+      missing = []
+      missing << 'type' unless type
+      missing << 'time' unless time
+      missing << 'hash' unless hash
+      unless missing.empty?
+        raise ArgumentError,
+              "event is missing required keys: #{missing.join(', ')}. " \
+              'Make sure you pass payload["event"], not the full webhook payload'
+      end
+
+      data = "#{type}@#{time}"
       calculated = OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new('SHA256'), webhook_id, data)
-      secure_compare(calculated, expected)
+      secure_compare(calculated, hash)
     end
 
     # @api private

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: signwell_sdk
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - SignWell
@@ -413,7 +413,7 @@ homepage: https://github.com/Bidsketch/signwell-sdk-ruby
 licenses:
 - MIT
 metadata:
-  documentation_uri: https://gemdocs.org/gems/signwell_sdk/0.1.0/
+  documentation_uri: https://gemdocs.org/gems/signwell_sdk/0.1.1/
   source_code_uri: https://github.com/Bidsketch/signwell-sdk-ruby
   homepage_uri: https://github.com/Bidsketch/signwell-sdk-ruby
   changelog_uri: https://github.com/Bidsketch/signwell-sdk-ruby/blob/main/CHANGELOG.md