feat(client): add webhook support

Author: stainless-app[bot]

Gemfile.lock

@@ -14,6 +14,7 @@ PATH
     imagekitio (4.2.0)
       cgi
       connection_pool
+      standardwebhooks
 
 GEM
   remote: https://rubygems.org/
@@ -143,6 +144,7 @@ GEM
       rexml (>= 3.2.6)
       sorbet-static-and-runtime (>= 0.5.10187)
       thor (>= 0.19.2)
+    standardwebhooks (1.0.1)
     steep (1.10.0)
       activesupport (>= 5.1)
       concurrent-ruby (>= 1.1.10)

imagekitio.gemspec

@@ -26,4 +26,5 @@ Gem::Specification.new do |s|
   s.extra_rdoc_files = ["README.md"]
   s.add_dependency "cgi"
   s.add_dependency "connection_pool"
+  s.add_dependency "standardwebhooks"
 end

lib/imagekitio.rb

@@ -30,6 +30,7 @@
 
 # Gems.
 require "connection_pool"
+require "standardwebhooks"
 
 # Package files.
 require_relative "imagekitio/version"

lib/imagekitio/client.rb

@@ -25,6 +25,13 @@ class Client < Imagekitio::Internal::Transport::BaseClient
     # @return [String, nil]
     attr_reader :password
 
+    # Your ImageKit webhook secret for verifying webhook signatures (starts with
+    # `whsec_`). You can find this in the
+    # [ImageKit dashboard](https://imagekit.io/dashboard/developer/webhooks). Only
+    # required if you're using webhooks.
+    # @return [String, nil]
+    attr_reader :webhook_secret
+
     # @return [Imagekitio::Resources::CustomMetadataFields]
     attr_reader :custom_metadata_fields
 
@@ -80,6 +87,11 @@ def base_url_overridden? = @base_url_overridden
     # dummy value. You can ignore this field. Defaults to
     # `ENV["OPTIONAL_IMAGEKIT_IGNORES_THIS"]`
     #
+    # @param webhook_secret [String, nil] Your ImageKit webhook secret for verifying webhook signatures (starts with
+    # `whsec_`). You can find this in the
+    # [ImageKit dashboard](https://imagekit.io/dashboard/developer/webhooks). Only
+    # required if you're using webhooks. Defaults to `ENV["IMAGEKIT_WEBHOOK_SECRET"]`
+    #
     # @param base_url [String, nil] Override the default base URL for the API, e.g.,
     # `"https://api.example.com/v2/"`. Defaults to `ENV["IMAGE_KIT_BASE_URL"]`
     #
@@ -93,6 +105,7 @@ def base_url_overridden? = @base_url_overridden
     def initialize(
       private_key: ENV["IMAGEKIT_PRIVATE_KEY"],
       password: ENV.fetch("OPTIONAL_IMAGEKIT_IGNORES_THIS", "do_not_set"),
+      webhook_secret: ENV["IMAGEKIT_WEBHOOK_SECRET"],
       base_url: ENV["IMAGE_KIT_BASE_URL"],
       max_retries: self.class::DEFAULT_MAX_RETRIES,
       timeout: self.class::DEFAULT_TIMEOUT_IN_SECONDS,
@@ -109,6 +122,7 @@ def initialize(
 
       @private_key = private_key.to_s
       @password = password.to_s
+      @webhook_secret = webhook_secret&.to_s
 
       super(
         base_url: base_url,

lib/imagekitio/resources/webhooks.rb

@@ -13,8 +13,18 @@ def unsafe_unwrap(payload)
 
       # @param payload [String] The raw webhook payload as a string
       #
+      # @param headers [Hash{String=>String}] The raw HTTP headers that came with the payload
+      #
+      # @param key [String, nil] The webhook signing key
+      #
       # @return [Imagekitio::Models::VideoTransformationAcceptedEvent, Imagekitio::Models::VideoTransformationReadyEvent, Imagekitio::Models::VideoTransformationErrorEvent, Imagekitio::Models::UploadPreTransformSuccessEvent, Imagekitio::Models::UploadPreTransformErrorEvent, Imagekitio::Models::UploadPostTransformSuccessEvent, Imagekitio::Models::UploadPostTransformErrorEvent]
-      def unwrap(payload)
+      def unwrap(payload, headers:, key: @client.webhook_secret)
+        if key.nil?
+          raise ArgumentError.new("Cannot verify a webhook without a key on either the client's webhook_secret or passed in as an argument")
+        end
+
+        ::StandardWebhooks::Webhook.new(key).verify(payload, headers)
+
         parsed = JSON.parse(payload, symbolize_names: true)
         Imagekitio::Internal::Type::Converter.coerce(Imagekitio::Models::UnwrapWebhookEvent, parsed)
       end

rbi/imagekitio/client.rbi

@@ -20,6 +20,13 @@ module Imagekitio
     sig { returns(T.nilable(String)) }
     attr_reader :password
 
+    # Your ImageKit webhook secret for verifying webhook signatures (starts with
+    # `whsec_`). You can find this in the
+    # [ImageKit dashboard](https://imagekit.io/dashboard/developer/webhooks). Only
+    # required if you're using webhooks.
+    sig { returns(T.nilable(String)) }
+    attr_reader :webhook_secret
+
     sig { returns(Imagekitio::Resources::CustomMetadataFields) }
     attr_reader :custom_metadata_fields
 
@@ -65,6 +72,7 @@ module Imagekitio
       params(
         private_key: T.nilable(String),
         password: T.nilable(String),
+        webhook_secret: T.nilable(String),
         base_url: T.nilable(String),
         max_retries: Integer,
         timeout: Float,
@@ -81,6 +89,11 @@ module Imagekitio
       # dummy value. You can ignore this field. Defaults to
       # `ENV["OPTIONAL_IMAGEKIT_IGNORES_THIS"]`
       password: ENV.fetch("OPTIONAL_IMAGEKIT_IGNORES_THIS", "do_not_set"),
+      # Your ImageKit webhook secret for verifying webhook signatures (starts with
+      # `whsec_`). You can find this in the
+      # [ImageKit dashboard](https://imagekit.io/dashboard/developer/webhooks). Only
+      # required if you're using webhooks. Defaults to `ENV["IMAGEKIT_WEBHOOK_SECRET"]`
+      webhook_secret: ENV["IMAGEKIT_WEBHOOK_SECRET"],
       # Override the default base URL for the API, e.g.,
       # `"https://api.example.com/v2/"`. Defaults to `ENV["IMAGE_KIT_BASE_URL"]`
       base_url: ENV["IMAGE_KIT_BASE_URL"],

rbi/imagekitio/resources/webhooks.rbi

@@ -23,7 +23,11 @@ module Imagekitio
       end
 
       sig do
-        params(payload: String).returns(
+        params(
+          payload: String,
+          headers: T::Hash[String, String],
+          key: T.nilable(String)
+        ).returns(
           T.any(
             Imagekitio::VideoTransformationAcceptedEvent,
             Imagekitio::VideoTransformationReadyEvent,
@@ -37,7 +41,11 @@ module Imagekitio
       end
       def unwrap(
         # The raw webhook payload as a string
-        payload
+        payload,
+        # The raw HTTP headers that came with the payload
+        headers:,
+        # The webhook signing key
+        key: @client.webhook_secret
       )
       end
 

sig/imagekitio/client.rbs

@@ -12,6 +12,8 @@ module Imagekitio
 
     attr_reader password: String?
 
+    attr_reader webhook_secret: String?
+
     attr_reader custom_metadata_fields: Imagekitio::Resources::CustomMetadataFields
 
     attr_reader files: Imagekitio::Resources::Files
@@ -39,6 +41,7 @@ module Imagekitio
     def initialize: (
       ?private_key: String?,
       ?password: String?,
+      ?webhook_secret: String?,
       ?base_url: String?,
       ?max_retries: Integer,
       ?timeout: Float,

sig/imagekitio/resources/webhooks.rbs

@@ -12,7 +12,9 @@ module Imagekitio
       | Imagekitio::UploadPostTransformErrorEvent)
 
       def unwrap: (
-        String payload
+        String payload,
+        headers: ::Hash[String, String],
+        ?key: String?
       ) -> (Imagekitio::VideoTransformationAcceptedEvent
       | Imagekitio::VideoTransformationReadyEvent
       | Imagekitio::VideoTransformationErrorEvent

test/imagekitio/resources/webhooks_test.rb

@@ -3,4 +3,30 @@
 require_relative "../test_helper"
 
 class Imagekitio::Test::Resources::WebhooksTest < Imagekitio::Test::ResourceTest
+  def test_unwrap
+    key = "whsec_c2VjcmV0Cg=="
+
+    webhook = StandardWebhooks::Webhook.new(key)
+
+    data =
+      "{\"id\":\"id\",\"type\":\"video.transformation.accepted\",\"created_at\":\"2019-12-27T18:11:19.117Z\",\"data\":{\"asset\":{\"url\":\"https://example.com\"},\"transformation\":{\"type\":\"video-transformation\",\"options\":{\"audio_codec\":\"aac\",\"auto_rotate\":true,\"format\":\"mp4\",\"quality\":0,\"stream_protocol\":\"HLS\",\"variants\":[\"string\"],\"video_codec\":\"h264\"}}},\"request\":{\"url\":\"https://example.com\",\"x_request_id\":\"x_request_id\",\"user_agent\":\"user_agent\"}}"
+    message_id = "1"
+    timestamp = Time.now.to_i.to_s
+    signature = webhook.sign(message_id, timestamp, data)
+    headers =
+      {"webhook-id" => message_id, "webhook-timestamp" => timestamp, "webhook-signature" => signature}
+
+    @image_kit.webhooks.unwrap(data, headers: headers, key: key)
+
+    bad_headers = [
+      headers.merge("webhook-id" => "bad"),
+      headers.merge("webhook-timestamp" => "0"),
+      headers.merge("webhook-signature" => webhook.sign(message_id, timestamp, "xxx"))
+    ]
+    bad_headers.each do |bad_header|
+      assert_raises(StandardWebhooks::WebhookVerificationError) do
+        @image_kit.webhooks.unwrap(data, headers: bad_header, key: key)
+      end
+    end
+  end
 end