Fourthwall.Client 0.1.0-dev2

Fourthwall.Client

A .NET client library for the Fourthwall Platform API and webhook processing.

Package	NuGet
Fourthwall.Client
Fourthwall.Client.AspNetCore
Fourthwall.Client.DependencyInjection
Fourthwall.Client.Generated

Features

• Kiota-generated REST client for the Fourthwall Platform API (shop data, webhooks, orders, memberships, etc.)
• Transport-neutral webhook handler — validate and deserialize incoming Fourthwall webhook deliveries
• Optional HMAC-SHA256 signature verification — enforce when you have a signing secret; skip when you don't
• ASP.NET Core integration — a single MapFourthwallWebhook() call wires up a fully functional webhook endpoint
• AOT-friendly — uses System.Text.Json source generation

Quick Start

1. Register services

builder.Services.AddFourthwallClient();

2. Map a webhook endpoint

app.MapFourthwallWebhook(
    "/webhooks/fourthwall",
    resolveWebhookOptionsAsync: (_, _) => Task.FromResult(new FourthwallWebhookOptions
    {
        // Leave SigningSecret null to skip signature verification.
        // Provide it to enforce HMAC-SHA256 validation.
        SigningSecret = configuration["Fourthwall:SigningSecret"],
        SignatureMode = FourthwallWebhookSignatureMode.ShopWebhook,
    }),
    onEventAsync: async (evt, httpContext, ct) =>
    {
        switch (evt)
        {
            case FourthwallOrderPlacedWebhookEvent order:
                Console.WriteLine($"New order: {order.Id}");
                break;

            case FourthwallDonationWebhookEvent donation:
                Console.WriteLine($"Donation: {donation.Id}");
                break;

            case FourthwallSubscriptionPurchasedWebhookEvent sub:
                Console.WriteLine($"New subscriber: {sub.Id}");
                break;
        }

        await Task.CompletedTask;
    });

3. Call the REST API

// Resolve the factory from DI or create it directly.
IFourthwallClientFactory factory = serviceProvider.GetRequiredService<IFourthwallClientFactory>();

FourthwallApiClient client = factory.CreateWithBasicAuth(new FourthwallBasicAuthOptions
{
    Username = "your-shop-username",
    Password = "your-shop-password",
});

// Register a webhook via the API.
WebhookConfigurationV1? webhook = await client.OpenApi.V10.Webhooks.PostAsync(
    new WebhookConfigurationCreateRequest
    {
        Url = "https://your-public-url/webhooks/fourthwall",
        AllowedTypes =
        [
            WebhookConfigurationCreateRequest_allowedTypes.ORDER_PLACED,
            WebhookConfigurationCreateRequest_allowedTypes.DONATION,
            WebhookConfigurationCreateRequest_allowedTypes.SUBSCRIPTION_PURCHASED,
        ],
    });

Packages

Signature Verification

Fourthwall signs webhook deliveries with HMAC-SHA256. Whether to verify is controlled by FourthwallWebhookOptions.SigningSecret:

// Skip verification — useful with Dev Tunnels / private endpoints.
new FourthwallWebhookOptions()

// Enforce shop webhook signatures.
new FourthwallWebhookOptions
{
    SigningSecret = "your-hmac-secret",
    SignatureMode = FourthwallWebhookSignatureMode.ShopWebhook,
}

// Enforce platform app webhook signatures.
new FourthwallWebhookOptions
{
    SigningSecret = "your-platform-app-secret",
    SignatureMode = FourthwallWebhookSignatureMode.PlatformAppWebhook,
}

Signature headers

Webhook Events

All events inherit from FourthwallWebhookEvent which carries Id, WebhookId, ShopId, Type, ApiVersion, CreatedAt, and TestMode.

Transport-neutral usage

FourthwallWebhookHandler works with any host — ASP.NET Core, Azure Functions, AWS Lambda, console apps, etc.:

FourthwallWebhookHandler handler = new(new FourthwallWebhookSignatureVerifier());

WebhookHandleResult<FourthwallWebhookEvent> result = await handler.HandleAsync(
    new WebhookRequest
    {
        Method  = request.Method,
        Path    = request.Path,
        ContentType = request.ContentType,
        Headers = ..., // Dictionary<string, string[]>
        Body    = requestBodyBytes,
    },
    new FourthwallWebhookOptions
    {
        SigningSecret = "optional-secret",
    });

if (result.IsAuthenticated && result.Event is FourthwallOrderPlacedWebhookEvent order)
{
    // handle order
}

Sample

The samples/Fourthwall.Client.Sample project is a fully automated interactive console that:

1. Prompts for Fourthwall API credentials (optional — for auto-registration)
2. Prompts for webhook path, port, and signing secret (all optional)
3. Starts an ASP.NET Core webhook receiver
4. Opens an Azure Dev Tunnels public HTTPS endpoint
5. Automatically registers (and deregisters on exit) the webhook via the Fourthwall API
6. Prints incoming events to the console in real time

Run it with:

cd samples/Fourthwall.Client.Sample
dotnet run

Requirements

• .NET 10+
• Fourthwall shop credentials (for REST API calls) — optional if you only need webhook receiving

License

MIT