diff --git a/README.md b/README.md index 6d69f1c..940a248 100644 --- a/README.md +++ b/README.md @@ -453,6 +453,11 @@ workspaces = seam.workspaces.list The Seam API implements webhooks using [Svix](https://www.svix.com). This SDK exports a thin wrapper `Seam::Webhook` around the svix package. Use it to parse and validate Seam webhook events. +Omitting the secret reads `SEAM_WEBHOOK_SECRET` when the helper is constructed. +An explicit secret, e.g. `Seam::Webhook.new("whsec_...")`, takes precedence over the environment. +A missing or non-string secret raises `TypeError`; an empty or decoded-empty secret raises +`Svix::EmptyWebhookSecretError` at construction. Explicit `nil` and empty strings are rejected, +not replaced by the environment value. Known event types load as `Seam::Resources::SeamEvent` subclasses with only that event's accessors; unknown types remain generic `SeamEvent` instances for forward compatibility. > [!TIP] @@ -462,7 +467,8 @@ Known event types load as `Seam::Resources::SeamEvent` subclasses with only that require "sinatra" require "seam" -webhook = Seam::Webhook.new(ENV["SEAM_WEBHOOK_SECRET"]) +# Set SEAM_WEBHOOK_SECRET before constructing the helper. +webhook = Seam::Webhook.new post "/webhook" do begin diff --git a/lib/seam/webhook.rb b/lib/seam/webhook.rb index 1c119fa..1eb3567 100644 --- a/lib/seam/webhook.rb +++ b/lib/seam/webhook.rb @@ -13,7 +13,14 @@ class InvalidWebhookPayloadError < Seam::Error end class Webhook - def initialize(secret) + def initialize(secret = ENV["SEAM_WEBHOOK_SECRET"]) + unless secret.is_a?(String) + raise TypeError, "Webhook secret must be a string; pass it explicitly or set SEAM_WEBHOOK_SECRET" + end + if secret.empty? + raise Svix::EmptyWebhookSecretError, "Pass a webhook secret or set SEAM_WEBHOOK_SECRET to a non-empty value" + end + @webhook = Svix::Webhook.new(secret) end diff --git a/spec/webhook_spec.rb b/spec/webhook_spec.rb index 2a3c693..b79c81f 100644 --- a/spec/webhook_spec.rb +++ b/spec/webhook_spec.rb @@ -23,6 +23,84 @@ def headers_for(payload, secret: self.secret, timestamp: Time.now.to_i, message_ {"svix-id" => message_id, "svix-timestamp" => timestamp.to_s, "svix-signature" => signature} end + describe "secret configuration" do + around do |example| + previous_secret = ENV.delete("SEAM_WEBHOOK_SECRET") + example.run + ensure + ENV["SEAM_WEBHOOK_SECRET"] = previous_secret + end + + it "verifies a signed event using only the environment secret" do + ENV["SEAM_WEBHOOK_SECRET"] = secret + + expect(described_class.new.verify(payload, headers_for(payload)).event_id).to eq("event-1") + end + + [nil, false, 123, {}].each do |invalid_secret| + it "rejects an explicit #{invalid_secret.inspect} despite a valid environment secret" do + ENV["SEAM_WEBHOOK_SECRET"] = secret + + expect { described_class.new(invalid_secret) }.to raise_error(TypeError, /Webhook secret must be a string/) + end + end + + it "prefers an explicit secret over the environment secret" do + environment_secret = "whsec_#{Base64.strict_encode64("environment-secret")}" + ENV["SEAM_WEBHOOK_SECRET"] = environment_secret + + expect(webhook.verify(payload, headers_for(payload)).event_id).to eq("event-1") + expect { webhook.verify(payload, headers_for(payload, secret: environment_secret)) } + .to raise_error(Seam::WebhookVerificationError) + end + + it "rejects an omitted secret when the environment secret is missing" do + expect { described_class.new }.to raise_error(TypeError, /SEAM_WEBHOOK_SECRET/) + end + + it "rejects nil when the environment secret is missing" do + expect { described_class.new(nil) }.to raise_error(TypeError, /SEAM_WEBHOOK_SECRET/) + end + + it "rejects an empty environment secret" do + ENV["SEAM_WEBHOOK_SECRET"] = "" + + expect { described_class.new }.to raise_error(Svix::EmptyWebhookSecretError, /SEAM_WEBHOOK_SECRET/) + end + + it "rejects an explicit empty secret despite a valid environment secret" do + ENV["SEAM_WEBHOOK_SECRET"] = secret + + expect { described_class.new("") }.to raise_error(Svix::EmptyWebhookSecretError, /SEAM_WEBHOOK_SECRET/) + end + + ["whsec_", " "].each do |empty_key| + it "rejects an environment secret that decodes to an empty key: #{empty_key.inspect}" do + ENV["SEAM_WEBHOOK_SECRET"] = empty_key + + expect { described_class.new }.to raise_error(Svix::EmptyWebhookSecretError) + end + + it "rejects an explicit decoded-empty key #{empty_key.inspect} despite a valid environment secret" do + ENV["SEAM_WEBHOOK_SECRET"] = secret + + expect { described_class.new(empty_key) }.to raise_error(Svix::EmptyWebhookSecretError) + end + end + + it "reads the environment at each construction without changing existing verifiers" do + ENV["SEAM_WEBHOOK_SECRET"] = secret + first = described_class.new + next_secret = "whsec_#{Base64.strict_encode64("next-secret")}" + ENV["SEAM_WEBHOOK_SECRET"] = next_secret + second = described_class.new + + expect(first.verify(payload, headers_for(payload)).event_id).to eq("event-1") + expect(second.verify(payload, headers_for(payload, secret: next_secret)).event_id).to eq("event-1") + expect { second.verify(payload, headers_for(payload)) }.to raise_error(Seam::WebhookVerificationError) + end + end + def invalid_payload_error(message) raise_error(Seam::InvalidWebhookPayloadError, message) end