Notavia.Sdk.AspNetCore 1.0.3

Notavia.Sdk.AspNetCore

ASP.NET Core Minimal API integration for receiving signed webhook events from Notavia. Provides MapWebhookHandler — a single call that registers a POST endpoint, verifies the HMAC-SHA256 signature on every request, and dispatches to your per-event callbacks.

Version: 1.0.2. Targets net8.0 and net10.0.

Install

dotnet add package Notavia.Sdk.AspNetCore

Requires Notavia.Sdk (pulled in automatically as a dependency).

Quick start

using NotifyService.Sdk.AspNetCore;

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.MapWebhookHandler("/webhooks/notify", new WebhookHandlerOptions
{
    SigningSecret = builder.Configuration["NotifyService:WebhookSecret"]!,

    OnNotificationSent = (evt, ct) =>
    {
        Console.WriteLine($"Sent: {evt.Id}  type={evt.Type}");
        return Task.CompletedTask;
    },

    OnNotificationFailed = (evt, ct) =>
    {
        Console.WriteLine($"Failed: {evt.Id}");
        return Task.CompletedTask;
    },
});

app.Run();

Configuration

The signing secret is shown once, when you create the endpoint under Settings → Webhooks in the Notavia console; it cannot be read back later, so store it as you would any other secret: Store it in user-secrets or an environment variable — never hard-code it.

dotnet user-secrets set "NotifyService:WebhookSecret" "whsec_YOUR_SECRET"

The secret may be provided as raw base64url or with the whsec_ prefix — both forms are accepted.

WebhookHandlerOptions reference

All callbacks have the signature Func<NotifyWebhookEvent<JsonElement>, CancellationToken, Task>. JsonElement is the raw payload — deserialize to a typed model as needed.

An event type with no matching callback is still verified and still passed to OnEvent; it is never an error. New event types can therefore be added without breaking your handler.

Event types

Paging on a provider outage

provider.critical is the machine-readable half of provider alerting — wire it to your pager and you will know a provider is down before your users tell you.

app.MapWebhookHandler("/webhooks/notify", new WebhookHandlerOptions
{
    SigningSecret = builder.Configuration["Notify:WebhookSecret"]!,
    OnProviderCritical = async (evt, ct) =>
    {
        ProviderAlert alert = evt.Data.Deserialize<ProviderAlert>()!;
        await pager.PageAsync(
            dedupeKey: evt.Id,
            title: $"{alert.Provider} is failing {alert.FailureRate}% of our {alert.Environment} mail",
            ct);
    },
    OnProviderRecovered = async (evt, ct) =>
    {
        ProviderAlert alert = evt.Data.Deserialize<ProviderAlert>()!;
        await pager.ResolveAsync(title: $"{alert.Provider} recovered", ct);
    },
});

public sealed record ProviderAlert(
    [property: JsonPropertyName("provider")] string Provider,
    [property: JsonPropertyName("environment")] string Environment,
    [property: JsonPropertyName("messages")] long Messages,
    [property: JsonPropertyName("failed_messages")] long FailedMessages,
    [property: JsonPropertyName("failure_rate")] double FailureRate,
    [property: JsonPropertyName("firing_since")] DateTimeOffset? FiringSince);

Two things worth knowing:

• messages and failed_messages count distinct messages, not delivery attempts. A single message the provider retried three times is one failed message, not three.
• Dedupe on evt.Id. It is stable for the life of one outage, so a retried webhook delivery carries the same id and will not page you twice for the same incident. A new outage on the same provider gets a new id.

HTTP response codes

Receiving all events in one handler

Use OnEvent when you want a single callback regardless of type:

app.MapWebhookHandler("/webhooks/notify", new WebhookHandlerOptions
{
    SigningSecret = config["NotifyService:WebhookSecret"]!,

    OnEvent = (evt, ct) =>
    {
        logger.LogInformation("Webhook received: {Type} id={Id}", evt.Type, evt.Id);
        return Task.CompletedTask;
    },
});

OnEvent and type-specific callbacks are not mutually exclusive — both fire when both are set.

Error handling in callbacks

Exceptions thrown inside a callback propagate to ASP.NET Core's exception-handling pipeline. Wrap your callback body in a try/catch or use the standard app.UseExceptionHandler middleware if you want to suppress errors and still return 200 OK to Notavia.

Notavia retries delivery when it receives a non-2xx response, so returning 200 OK after logging an error is the correct recovery pattern for transient processing failures.

Low-level signature verification

If you need to verify signatures outside of MapWebhookHandler (e.g., in a controller or middleware), use WebhookSignatures.Verify from NotifyService.Sdk directly:

using NotifyService.Sdk;

bool valid = WebhookSignatures.Verify(
    rawBody: rawBodyString,
    signatureHeader: request.Headers["NotifyService-Signature"].ToString(),
    signingSecret: config["NotifyService:WebhookSecret"]!);

License

MIT.