Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 7 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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]
Expand All @@ -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
Expand Down
9 changes: 8 additions & 1 deletion lib/seam/webhook.rb
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
78 changes: 78 additions & 0 deletions spec/webhook_spec.rb
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Loading