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 @@ -253,14 +253,20 @@ await seam.Devices.UpdateAsync(new()
Verify and parse incoming Seam webhook events with `SeamWebhook`:

```csharp
var webhook = new SeamWebhook(Environment.GetEnvironmentVariable("SEAM_WEBHOOK_SECRET")!);
var webhook = new SeamWebhook(); // Reads SEAM_WEBHOOK_SECRET.

var seamEvent = webhook.Verify(requestBody, requestHeaders);

if (seamEvent is Seam.Models.EventDeviceConnected connected)
Console.WriteLine(connected.DeviceId);
```

Omitting the secret reads `SEAM_WEBHOOK_SECRET` when
the helper is constructed. Pass `new SeamWebhook("whsec_...")` to override
the environment. A missing or empty secret raises `InvalidOperationException`
at construction; explicit null or empty strings never fall back to the environment.
Svix also rejects secrets that decode to an empty signing key.

Verification failures raise Svix's `WebhookVerificationException`: treat the
payload as forged and respond with an error status so Svix retries. A payload
that is correctly signed but unreadable raises a
Expand Down
26 changes: 24 additions & 2 deletions src/Seam/SeamWebhook.cs
Original file line number Diff line number Diff line change
Expand Up @@ -12,17 +12,39 @@ namespace Seam
/// by the API. Verification failures raise
/// <see cref="Svix.Exceptions.WebhookVerificationException"/>.
/// <code>
/// var webhook = new SeamWebhook(Environment.GetEnvironmentVariable("SEAM_WEBHOOK_SECRET")!);
/// var webhook = new SeamWebhook(); // Reads SEAM_WEBHOOK_SECRET.
/// var seamEvent = webhook.Verify(requestBody, requestHeaders);
/// </code>
/// </remarks>
public sealed class SeamWebhook
{
private readonly Svix.Webhook _webhook;

/// <param name="secret">The webhook secret from the Seam Console.</param>
/// <summary>
/// Reads SEAM_WEBHOOK_SECRET at construction time.
/// </summary>
/// <exception cref="InvalidOperationException">
/// When the environment secret is missing or empty.
/// </exception>
public SeamWebhook()
: this(Environment.GetEnvironmentVariable("SEAM_WEBHOOK_SECRET") ?? "") { }

/// <param name="secret">
/// The webhook secret from the Seam Console. Null and empty strings never fall back
/// to SEAM_WEBHOOK_SECRET.
/// </param>
/// <exception cref="InvalidOperationException">
/// When the secret is missing or empty.
/// </exception>
public SeamWebhook(string secret)
{
if (string.IsNullOrEmpty(secret))
{
throw new InvalidOperationException(
"Provide a webhook secret or set SEAM_WEBHOOK_SECRET to a non-empty value."
);
}

_webhook = new Svix.Webhook(secret);
}

Expand Down
75 changes: 75 additions & 0 deletions test/Seam.Test/SeamWebhookTests.cs
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@ namespace Seam.Test;
using System.Security.Cryptography;
using System.Text;
using System.Text.Json;
using Seam.Test.Support;
using Svix.Exceptions;

public class SeamWebhookTests
Expand Down Expand Up @@ -36,6 +37,80 @@ private static Dictionary<string, string> SignedHeaders(
};
}

[Fact]
public void OmittedSecretReadsEnvironment()
{
using var env = new EnvGuard();
env.Set("SEAM_WEBHOOK_SECRET", Secret);

var webhook = new SeamWebhook();
var seamEvent = webhook.Verify(Payload, SignedHeaders(Payload));

Assert.Equal("device.connected", seamEvent.EventType);
}

[Fact]
public void ExplicitSecretOverridesEnvironment()
{
using var env = new EnvGuard();
env.Set("SEAM_WEBHOOK_SECRET", "whsec_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=");

var seamEvent = new SeamWebhook(Secret).Verify(Payload, SignedHeaders(Payload));

Assert.Equal("device.connected", seamEvent.EventType);
}

[Theory]
[InlineData(null)]
[InlineData("")]
public void MissingOrEmptyEnvironmentSecretIsRejected(string? secret)
{
using var env = new EnvGuard();
if (secret is not null)
env.Set("SEAM_WEBHOOK_SECRET", secret);

var exception = Assert.Throws<InvalidOperationException>(() => new SeamWebhook());
Assert.Contains("SEAM_WEBHOOK_SECRET", exception.Message);
}

[Theory]
[InlineData(null)]
[InlineData("")]
public void ExplicitNullOrEmptySecretDoesNotFallBackToEnvironment(string? secret)
{
using var env = new EnvGuard();
env.Set("SEAM_WEBHOOK_SECRET", Secret);

Assert.Throws<InvalidOperationException>(() => new SeamWebhook(secret!));
}

[Theory]
[InlineData("whsec_")]
[InlineData("whsec_ ")]
[InlineData(" ")]
public void EnvironmentSecretWithEmptyDecodedKeyIsRejected(string secret)
{
using var env = new EnvGuard();
env.Set("SEAM_WEBHOOK_SECRET", secret);

Assert.Throws<EmptyWebhookSecretException>(() => new SeamWebhook());
}

[Fact]
public void EachConstructionReadsCurrentEnvironment()
{
using var env = new EnvGuard();
env.Set("SEAM_WEBHOOK_SECRET", Secret);
var first = new SeamWebhook();

env.Set("SEAM_WEBHOOK_SECRET", "whsec_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=");
var second = new SeamWebhook();
var headers = SignedHeaders(Payload);

Assert.Equal("device.connected", first.Verify(Payload, headers).EventType);
Assert.Throws<WebhookVerificationException>(() => second.Verify(Payload, headers));
}

[Fact]
public void VerifyReturnsTheEvent()
{
Expand Down
1 change: 1 addition & 0 deletions test/Seam.Test/Support/EnvGuard.cs
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@ public sealed class EnvGuard : IDisposable
"SEAM_PERSONAL_ACCESS_TOKEN",
"SEAM_WORKSPACE_ID",
"SEAM_ENDPOINT",
"SEAM_WEBHOOK_SECRET",
};

private readonly Dictionary<string, string?> _saved = new();
Expand Down
Loading