Skip to content

feat: support SEAM_WEBHOOK_SECRET in webhook helper - #346

Merged
razor-x merged 3 commits into
mainfrom
fm/webhook-env-csharp
Nov 17, 2026
Merged

razor-x merged 3 commits into
mainfrom
fm/webhook-env-csharp

Conversation

@razor-x

@razor-x razor-x commented Nov 17, 2026 •

Copy link
Copy Markdown
Member

Intent

Add SEAM_WEBHOOK_SECRET support to this maintained Seam SDK webhook helper and open a PR. This should be a small change: omitted constructor secret reads SEAM_WEBHOOK_SECRET; an explicitly supplied secret takes precedence. Preserve existing webhook verification semantics and idiomatic constructor usage. Include focused tests and examples. This is one of five parallel SDK PRs. No merge requested.

passing null for php etc should not be allowed here, it is an optional argument and only uses env when not passed in. other values would be an error

What Changed

  • Add a parameterless SeamWebhook constructor that reads SEAM_WEBHOOK_SECRET at construction time; explicitly supplied secrets take precedence.
  • Reject missing or empty secrets without falling back for explicit null or empty arguments, while retaining Svix verification.
  • Add focused environment-secret tests and update webhook usage examples.

Risk Assessment

✅ Low: The bounded constructor change distinguishes omission from explicit null, preserves Svix verification, and includes focused behavioral coverage.

Testing

Four real-SDK consumer scenarios and 26 focused webhook tests passed on .NET 10. Retained runtime evidence and driver source; cleaned disposable files and stopped build servers. Restore emitted nonblocking cache/audit permission warnings. No UI surface or tenant validation; .NET 8 runtime was unavailable.

  • Live validation: ✅ go - 4 of 4 scenarios driven live against the product
Scenario Result Live Evidence
Local SDK consumer reads the environment on construction and retains each instance's signing key ✅ pass live Real SDK consumer transcript: environment constructor and construction-time snapshot
Local SDK consumer verifies with an explicit secret despite different, malformed, or missing environment values ✅ pass live Real SDK consumer transcript: explicit secret overrides environment
Local SDK consumer rejects unusable environment secrets and explicit null or empty secrets without fallback ✅ pass live Real SDK consumer transcript: missing, empty, malformed, null and whitespace secrets
Environment-backed local SDK verifies synthetic events and rejects forged, expired, incomplete, or unreadable webhooks ✅ pass live Real SDK consumer transcript: authentication and payload guards
Evidence: Real SDK consumer transcript

Real SDK consumer accepted independently signed events and rejected invalid secrets, tampered bodies, wrong keys, expired signatures, and missing signatures.

SCENARIO environment constructor and construction-time snapshot
ACCEPT event_id=8d7e0b26-5e6c-4a1f-9b3d-1b0f0e5a9c11 event_type=device.connected
ACCEPT event_id=8d7e0b26-5e6c-4a1f-9b3d-1b0f0e5a9c11 event_type=device.connected
ACCEPT event_id=8d7e0b26-5e6c-4a1f-9b3d-1b0f0e5a9c11 event_type=device.connected
REJECT second instance rejects old key: WebhookVerificationException
SCENARIO explicit secret overrides environment, including unusable environment
ACCEPT event_id=8d7e0b26-5e6c-4a1f-9b3d-1b0f0e5a9c11 event_type=device.connected
ACCEPT event_id=8d7e0b26-5e6c-4a1f-9b3d-1b0f0e5a9c11 event_type=device.connected
ACCEPT event_id=8d7e0b26-5e6c-4a1f-9b3d-1b0f0e5a9c11 event_type=device.connected
SCENARIO missing, empty, malformed, null and whitespace secrets cannot fall back
REJECT missing env: InvalidOperationException
REJECT empty env: InvalidOperationException
REJECT explicit null with valid env: InvalidOperationException
REJECT explicit empty with valid env: InvalidOperationException
REJECT empty decoded env key: EmptyWebhookSecretException
REJECT empty decoded env key: EmptyWebhookSecretException
REJECT empty decoded env key: EmptyWebhookSecretException
REJECT malformed env: FormatException
SCENARIO environment-backed verification retains authentication and payload guards
ACCEPT event_id=8d7e0b26-5e6c-4a1f-9b3d-1b0f0e5a9c11 event_type=device.connected
REJECT tampered body: WebhookVerificationException
REJECT wrong signing key: WebhookVerificationException
REJECT expired signature: WebhookVerificationException
REJECT missing signature: WebhookVerificationException
REJECT authenticated invalid JSON: SeamInvalidWebhookPayloadException
All real SDK consumer scenarios completed.
Evidence: Disposable consumer source and independent HMAC oracle
using System.Security.Cryptography;
using System.Text;
using Seam;
using Svix.Exceptions;

// Independent oracle: Svix wire protocol signs id.timestamp.rawBody with HMAC-SHA256.
const string a = "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw";
const string b = "whsec_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=";
const string payload = "{\"event_id\":\"8d7e0b26-5e6c-4a1f-9b3d-1b0f0e5a9c11\",\"event_type\":\"device.connected\"}";
Dictionary<string,string> Sign(string body, string secret = a, int age = 0) {
    var ts = DateTimeOffset.UtcNow.AddMinutes(age).ToUnixTimeSeconds().ToString();
    var signature = Convert.ToBase64String(HMACSHA256.HashData(Convert.FromBase64String(secret[6..]), Encoding.UTF8.GetBytes($"msg_live.{ts}.{body}")));
    return new() { ["SVIX-ID"] = "msg_live", ["SVIX-TIMESTAMP"] = ts, ["SVIX-SIGNATURE"] = $"v1,{signature}" };
}
void Accept(SeamWebhook webhook, string body = payload, string secret = a) {
    var ev = webhook.Verify(body, Sign(body, secret));
    if (ev.EventId != "8d7e0b26-5e6c-4a1f-9b3d-1b0f0e5a9c11" || ev.EventType != "device.connected") throw new Exception("Unexpected event");
    Console.WriteLine($"ACCEPT event_id={ev.EventId} event_type={ev.EventType}");
}
void Reject<T>(string name, Action action) where T: Exception {
    try { action(); } catch (T e) { Console.WriteLine($"REJECT {name}: {e.GetType().Name}"); return; }
    throw new Exception($"Expected {typeof(T).Name}: {name}");
}
Environment.SetEnvironmentVariable("SEAM_WEBHOOK_SECRET", a);
Console.WriteLine("SCENARIO environment constructor and construction-time snapshot");
var first = new SeamWebhook(); Accept(first);
Environment.SetEnvironmentVariable("SEAM_WEBHOOK_SECRET", b);
var second = new SeamWebhook(); Accept(second, secret:b); Accept(first);
Reject<WebhookVerificationException>("second instance rejects old key", () => second.Verify(payload, Sign(payload)));
Console.WriteLine("SCENARIO explicit secret overrides environment, including unusable environment");
Accept(new SeamWebhook(secret:a));
Environment.SetEnvironmentVariable("SEAM_WEBHOOK_SECRET", "not base64!"); Accept(new SeamWebhook(a));
Environment.SetEnvironmentVariable("SEAM_WEBHOOK_SECRET", null); Accept(new SeamWebhook(a));
Console.WriteLine("SCENARIO missing, empty, malformed, null and whitespace secrets cannot fall back");
foreach (var value in new string?[]{null,""}) {
 Environment.SetEnvironmentVariable("SEAM_WEBHOOK_SECRET", value);
 Reject<InvalidOperationException>(value is null ? "missing env" : "empty env", () => new SeamWebhook());
}
Environment.SetEnvironmentVariable("SEAM_WEBHOOK_SECRET", a);
Reject<InvalidOperationException>("explicit null with valid env", () => new SeamWebhook(null!));
Reject<InvalidOperationException>("explicit empty with valid env", () => new SeamWebhook(""));
foreach (var value in new[]{"whsec_", "whsec_   ", "   ", "not base64!"}) {
 Environment.SetEnvironmentVariable("SEAM_WEBHOOK_SECRET", value);
 if (value == "not base64!") Reject<FormatException>("malformed env", () => new SeamWebhook());
 else Reject<EmptyWebhookSecretException>("empty decoded env key", () => new SeamWebhook());
}
Console.WriteLine("SCENARIO environment-backed verification retains authentication and payload guards");
Environment.SetEnvironmentVariable("SEAM_WEBHOOK_SECRET", a);
var verifier = new SeamWebhook(); Accept(verifier);
Reject<WebhookVerificationException>("tampered body", () => verifier.Verify(payload.Replace("connected", "disconnected"), Sign(payload)));
Reject<WebhookVerificationException>("wrong signing key", () => verifier.Verify(payload, Sign(payload,b)));
Reject<WebhookVerificationException>("expired signature", () => verifier.Verify(payload, Sign(payload, age:-10)));
var missing = Sign(payload); missing.Remove("SVIX-SIGNATURE");
Reject<WebhookVerificationException>("missing signature", () => verifier.Verify(payload,missing));
Reject<SeamInvalidWebhookPayloadException>("authenticated invalid JSON", () => verifier.Verify("not json",Sign("not json")));
Console.WriteLine("All real SDK consumer scenarios completed.");

Pipeline

Updates from git push no-mistakes

✅ **Intent** - passed

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

⚠️ **Review** - 1 warning
  • 🚨 src/Seam/SeamWebhook.cs:30 - Intent requires "only uses env when not passed in" and "passing null ... should not be allowed"; the added public SeamWebhook(string? secret = null) and secret ??= Environment.GetEnvironmentVariable(...) instead accept explicit null. With SEAM_WEBHOOK_SECRET set, new SeamWebhook(null) silently succeeds using that key. Remove this unrequired null fallback: use a parameterless environment-reading constructor and an explicit-secret constructor that rejects null. The same contract must change at src/Seam/SeamWebhook.cs:24 (XML documentation), README.md:264 (null example), test/Seam.Test/SeamWebhookTests.cs:39-48 (null acceptance), and test/Seam.Test/SeamWebhookTests.cs:76 (null rejection currently depends on missing environment).

🔧 Fix applied.
1 warning still open:

  • ⚠️ .dotnet/.dotnet/10.0.400.aspNetCertificateSentinel:1 - Remove the SDK first-run sentinel artifacts: no webhook-environment requirement needs them. The fix round introduced these machine-local tool-state files, unrelated to the minimal constructor fix. Also remove .dotnet/.dotnet/10.0.400.dotnetFirstUseSentinel:1 and .dotnet/.dotnet/10.0.400.toolpath.sentinel:1 (all three files are empty).

🔧 Fix applied.
1 warning still open:

  • ⚠️ .dotnet/.dotnet/10.0.400.aspNetCertificateSentinel:1 - Remove the SDK first-run sentinel artifacts: no webhook-environment requirement needs them. The fix round introduced these machine-local tool-state files, unrelated to the minimal constructor fix. Also remove .dotnet/.dotnet/10.0.400.dotnetFirstUseSentinel:1 and .dotnet/.dotnet/10.0.400.toolpath.sentinel:1 (all three files are empty).
✅ **Test** - passed

✅ No issues found.

  • Live validation: ✅ go - 4 of 4 scenarios driven live against the product
Scenario Result Live Evidence
Local SDK consumer reads the environment on construction and retains each instance's signing key ✅ pass live Real SDK consumer transcript: environment constructor and construction-time snapshot
Local SDK consumer verifies with an explicit secret despite different, malformed, or missing environment values ✅ pass live Real SDK consumer transcript: explicit secret overrides environment
Local SDK consumer rejects unusable environment secrets and explicit null or empty secrets without fallback ✅ pass live Real SDK consumer transcript: missing, empty, malformed, null and whitespace secrets
Environment-backed local SDK verifies synthetic events and rejects forged, expired, incomplete, or unreadable webhooks ✅ pass live Real SDK consumer transcript: authentication and payload guards
  • dotnet run --project .validation/WebhookSmoke.csproj -p:RunAnalyzers=false
  • dotnet test test/Seam.Test/Seam.Test.csproj -f net10.0 --filter FullyQualifiedName~SeamWebhookTests -p:RunAnalyzers=false — 26 passed
  • dotnet .validation/bin/Debug/net10.0/WebhookSmoke.dll — retained runtime transcript
  • dotnet build-server shutdown; removed disposable consumer and newly created build outputs; verified clean worktree
✅ **Document** - passed

✅ No issues found.

✅ **Lint** - passed

✅ No issues found.

✅ **Push** - passed

✅ No issues found.

@razor-x
razor-x merged commit fac393d into main Nov 17, 2026
14 checks passed
@razor-x
razor-x deleted the fm/webhook-env-csharp branch November 17, 2026 21:57
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant