Whisperr 1.0.0

Whisperr .NET SDK

Server-side SDK for .NET - reliable churn-signal event tracking for ASP.NET Core, workers, serverless handlers, and any backend that knows the end-user id.

dotnet add package Whisperr

Quick Start

using Whisperr;

var whisperr = new WhisperrClient(Environment.GetEnvironmentVariable("WHISPERR_API_KEY")!);

whisperr.Track(
    "user_8842",
    "payment_failed",
    new Dictionary<string, object?>
    {
        ["amount_cents"] = 4900,
        ["reason"] = "card_declined"
    });

whisperr.Identify("user_8842", new IdentifyOptions
{
    Email = "ada@example.com",
    Traits = new Dictionary<string, object?>
    {
        ["plan"] = "pro"
    }
});

await whisperr.ShutdownAsync();

The user id is always explicit. Pass the same external_user_id that your app uses everywhere else, and backend events land on the same Whisperr timeline as frontend events.

ASP.NET Core

Install the companion package for dependency-injection wiring:

dotnet add package Whisperr.AspNetCore

AddWhisperr binds the Whisperr configuration section and falls back to the WHISPERR_API_KEY environment variable, then registers WhisperrClient as a singleton. The host disposes the singleton on shutdown, which runs a final flush, so you do not need to manage the lifetime yourself.

using Whisperr.AspNetCore;

builder.Services.AddWhisperr(builder.Configuration, options =>
{
    options.OnError = error => Console.Error.WriteLine($"whisperr:{error.Code} {error.Message}");
});

// appsettings.json
{
  "Whisperr": {
    "ApiKey": "wrk_...",
    "FlushInterval": "00:00:10"
  }
}

Inject WhisperrClient wherever you have the user id. Track/Identify enqueue and return immediately; let the background flush and host-shutdown flush deliver them, rather than awaiting FlushAsync on the request path (a flush can wait through retry backoff):

app.MapPost("/billing/webhook", (
    BillingWebhook webhook,
    WhisperrClient whisperr) =>
{
    whisperr.Track(webhook.UserId, "payment_failed", new Dictionary<string, object?>
    {
        ["amount_cents"] = webhook.AmountCents,
        ["provider"] = "stripe"
    });

    return Results.Ok();
});

Request-scoped tracking

For request handlers that already authenticate a user, add the middleware after authentication and use HttpContext.Whisperr(), which binds to the user id from the NameIdentifier/sub claim (override via UseWhisperr(resolveUser)):

using Whisperr.AspNetCore;

app.UseAuthentication();
app.UseWhisperr();

app.MapPost("/plan/upgrade", (HttpContext http) =>
{
    http.Whisperr().Track("plan_upgraded", new Dictionary<string, object?> { ["plan"] = "pro" });
    return Results.Ok();
});

Behavior

• Track and Identify enqueue in memory and return immediately.
• Events flush in batches to /v1/events/batch; identity updates flush to /v1/identify.
• Requests use X-API-Key.
• event_type must be lowercase snake_case; invalid events are dropped before they can poison a batch.
• Each event gets a stable $message_id idempotency key in context; retries reuse the same id.
• 401/403 retain the batch and surface auth.
• 429, 5xx, timeouts, and network failures retry with bounded backoff; after retries are exhausted, the batch is retained and retry_exhausted is surfaced.
• Other 4xx responses drop the offending batch and surface dropped.

The queue is in-process, not crash-durable. Call FlushAsync or ShutdownAsync before short-lived processes exit.

Runtime support

• Targets: net8.0 and netstandard2.0 (the latter covers .NET Framework 4.7.2+ and other netstandard2.0 hosts). The conformance suite runs on both net8.0 and net472 in CI.
• Long-lived hosts: hold one client for the process lifetime. In ASP.NET Core the DI singleton is disposed (and flushed) on shutdown.
• Short-lived / serverless: the background timer cannot guarantee delivery before the runtime freezes — await client.ShutdownAsync() (or FlushAsync()) before returning so buffered events aren't lost.
• Trimming / AOT: standard server apps (including trimmed deployments) are supported. The SDK uses reflection-based System.Text.Json, so Native AOT is not a v1 guarantee; prefer the JIT/ReadyToRun runtimes for now.

Options

Development

The tests consume whisperr-spec fixtures. In this workspace the sibling ../whisperr-spec repo is picked up automatically. In CI or another checkout:

export WHISPERR_SPEC_PATH=/path/to/whisperr-spec/conformance/wire.json
dotnet test

Build and pack:

dotnet test -c Release
dotnet pack src/Whisperr/Whisperr.csproj -c Release -o artifacts

Publish to NuGet. Releases are cut by pushing a v*.*.* tag (the workflow derives the package version from the tag), but you can also push locally:

dotnet nuget push artifacts/Whisperr.*.nupkg \
  --source https://api.nuget.org/v3/index.json \
  --api-key "$NUGET_API_KEY" \
  --skip-duplicate

Whisperr - predict churn, automate interventions, recover revenue. whisperr.net