Skip to content
← Alle Beiträge
· Delta1 Labs WebhooksKeyright

Eingehende Billing-Webhooks in .NET verifizieren

Ihr Lizenzserver vertraut einem POST Ihres Zahlungsanbieters, bis ein Angreifer seinen eigenen schickt. Wie man eingehende, HMAC-signierte Webhooks korrekt verifiziert: Signatur über die Rohbytes, zeitkonstanter Vergleich, Zeitstempeltoleranz und Replay-Schutz, und anschließend eine Rückerstattung mit der Lizenzsperrung abgleicht.

Ein Lizenzserver ist nur so vertrauenswürdig wie die Ereignisse, auf die er reagiert. Wird ein Kunde erstattet, sendet Ihr Zahlungsanbieter einen Webhook; Ihr Back-End sperrt die Lizenz; die nächste Verifizierung schlägt geschlossen fehl. Die gesamte Kette hängt an einer Annahme: dass der POST wirklich vom Anbieter kam. Nehmen Sie diese weg, und jeder, der die Endpunkt-URL kennt, kann die Lizenz eines Wettbewerbers sperren oder sich selbst eine unbefristete gewähren, mit einem einzigen curl.

Anbieter lösen das, indem sie jeden Webhook mit einem gemeinsamen Geheimnis signieren. Die Signatur ist nur so gut wie Ihre Verifizierung, und genau dort gehen die meisten Integrationen still schief.

Die eigentliche Frage

Was genau verifizieren Sie, und wogegen? Ein naiver Handler greift auf den bereits geparsten Body und einen Zeichenkettenvergleich zurück:

// WRONG on three counts
app.MapPost("/billing/webhook", (BillingEvent evt, HttpRequest req) =>
{
    var sig = req.Headers["X-Signature"].ToString();
    var expected = Convert.ToHexString(Hmac(JsonSerializer.SerializeToUtf8Bytes(evt)));
    if (sig == expected) Apply(evt);   // (1) re-serialized body (2) == compare (3) no freshness
    return Results.Ok();
});

Jede Zeile hier ist eine Lücke. Der Body wurde neu serialisiert, also stimmen die Bytes nicht mehr mit dem Signierten überein. Der Vergleich ist ==, was Timing verrät. Und nichts hindert einen Angreifer daran, einen echten Webhook aufzuzeichnen und ihn tausendmal erneut abzuspielen. Beheben wir alle drei.

Der signierte Inhalt

Ein typischer Anbieter sendet einen Header, der sowohl einen Zeitstempel als auch eine oder mehrere Signaturen trägt:

X-Keyright-Signature: t=1763305200,v1=4f2d...e9 (64 hex chars)

Die Signatur v1 ist HMAC-SHA256(secret, signedContent), und der signierte Inhalt ist nicht der Body allein, sondern der Zeitstempel, ein Trennzeichen und die Rohbytes des Bodys aneinandergehängt:

signedContent = "1763305200" + "." + <raw request body bytes>

Den Zeitstempel in das HMAC einzubinden, ist das, was den Replay-Schutz ermöglicht: Sie können die Signatur nicht behalten und über ihren Ausstellungszeitpunkt lügen, weil die Zeit Teil des Signierten ist.

Rohbytes vor dem Binding t . body signierter Inhalt HMAC-SHA256 Schlüssel = Secret FixedTimeEquals erwartet vs v1 Zeitfenster ablehnen bei |now - t| > 5m Replay-Cache bekannte id ablehnen Annehmen Lizenz abgleichen 401 Unauthorized wenn ein Tor versagt
Vier unabhängige Tore. Echtheit (HMAC), Integrität (dieselben Rohbytes), Aktualität (Zeitfenster) und Einmaligkeit (Replay-Cache) müssen alle passieren, bevor ein Billing-Ereignis den Lizenzzustand berührt.

Der Verifizierer

Hier ein korrekter Verifizierer. Er parst den Header, erzwingt das Zeitfenster, berechnet das HMAC über den exakten signierten Inhalt neu und vergleicht in konstanter Zeit.

using System.Globalization;
using System.Security.Cryptography;
using System.Text;

public sealed class WebhookVerifier(string signingSecret)
{
    private readonly byte[] _secret = Encoding.UTF8.GetBytes(signingSecret);
    private readonly TimeSpan _tolerance = TimeSpan.FromMinutes(5);

    public bool TryVerify(byte[] rawBody, string signatureHeader, DateTimeOffset now)
    {
        if (!TryParseHeader(signatureHeader, out long ts, out byte[] provided))
            return false;

        // Freshness: a valid signature is not a fresh one.
        var skew = now - DateTimeOffset.FromUnixTimeSeconds(ts);
        if (skew.Duration() > _tolerance)
            return false;

        // Signed content is exactly: "<t>." followed by the raw body bytes.
        byte[] prefix = Encoding.ASCII.GetBytes(
            ts.ToString(CultureInfo.InvariantCulture) + ".");
        byte[] signed = new byte[prefix.Length + rawBody.Length];
        Buffer.BlockCopy(prefix, 0, signed, 0, prefix.Length);
        Buffer.BlockCopy(rawBody, 0, signed, prefix.Length, rawBody.Length);

        byte[] expected = HMACSHA256.HashData(_secret, signed);

        // Constant-time: never ==.
        return CryptographicOperations.FixedTimeEquals(expected, provided);
    }

    private static bool TryParseHeader(string header, out long ts, out byte[] v1)
    {
        ts = 0; v1 = [];
        if (string.IsNullOrEmpty(header)) return false;
        foreach (var part in header.Split(','))
        {
            var kv = part.Split('=', 2);
            if (kv.Length != 2) continue;
            switch (kv[0].Trim())
            {
                case "t":
                    if (!long.TryParse(kv[1], NumberStyles.None,
                        CultureInfo.InvariantCulture, out ts)) return false;
                    break;
                case "v1":
                    try { v1 = Convert.FromHexString(kv[1].Trim()); }
                    catch (FormatException) { return false; }
                    break;
            }
        }
        return ts != 0 && v1.Length == 32; // SHA-256 is 32 bytes
    }
}

Drei Details tragen die Sicherheit. HMACSHA256.HashData verwendet das gemeinsame Geheimnis als Schlüssel des Hashs, sodass nur, wer es besitzt, einen passenden Digest erzeugen kann. FixedTimeEquals vergleicht alle 32 Bytes, unabhängig davon, wo sie zuerst abweichen, sodass kein Timing-Orakel durchsickert. Und der Zeitstempel steckt in signed, kann also nicht geändert werden, ohne v1 ungültig zu machen.

Die exakten Bytes erfassen

Der Verifizierer ist nutzlos, wenn Sie ihm die falschen Bytes übergeben. In ASP.NET Core liest und verwirft das Framework den Anfrage-Stream, sobald Sie ein Model binden, und selbst wenn Sie das geparste Objekt erneut serialisieren, erhalten Sie andere Bytes als die vom Anbieter signierten. Lesen Sie zuerst den rohen Body:

app.MapPost("/billing/webhook",
    async (HttpRequest req, WebhookVerifier verifier, IReplayCache seen,
           ILicenseStore store) =>
{
    using var ms = new MemoryStream();
    await req.Body.CopyToAsync(ms);
    byte[] raw = ms.ToArray();               // exactly what was signed

    var sig = req.Headers["X-Keyright-Signature"].ToString();
    if (!verifier.TryVerify(raw, sig, DateTimeOffset.UtcNow))
        return Results.Unauthorized();        // 401: one message for every failure

    var evt = JsonSerializer.Deserialize<BillingEvent>(raw)!;

    // Replay defense: ack duplicates without re-applying them.
    if (!await seen.TryAddAsync(evt.Id, TimeSpan.FromHours(24)))
        return Results.Ok();

    await Reconcile(evt, store);
    return Results.Ok();
});

Erst nach der Verifizierung ist das Deserialisieren sicher. Der Replay-Cache speichert jede Ereignis-id mit einer TTL, die den Wiederholungshorizont des Anbieters bequem übersteigt; eine zweite Zustellung derselben id wird mit 200 quittiert, tut aber nichts. 200 statt eines Fehlers zurückzugeben, ist Absicht: Das Ereignis wurde behandelt, also soll der Anbieter nicht weiter wiederholen.

Mit dem Lizenzzustand abgleichen

Mit einem vertrauenswürdigen Ereignis in der Hand ist die Zuordnung zu Keyright klein. Eine Rückerstattung oder ein Chargeback sperren; eine erfolgreiche Verlängerung verlängert. Halten Sie den Switch eng und scheitern Sie geschlossen bei allem Unerwarteten:

static async Task Reconcile(BillingEvent evt, ILicenseStore store) =>
    _ = evt.Type switch
    {
        "charge.refunded"        => await store.RevokeByOrderAsync(evt.OrderId, evt.Type),
        "charge.dispute.created" => await store.RevokeByOrderAsync(evt.OrderId, evt.Type),
        "subscription.renewed"   => await store.ExtendByOrderAsync(evt.OrderId, evt.PeriodEnd),
        _                        => false // unknown types are logged, not trusted
    };

Nach der Sperrung schlägt die nächste SDK-Verifizierung geschlossen fehl, und die Berechtigungen des Kunden – eine vom Anbieter gewählte Menge wie max_projects, feature.export oder max_major_version – werden nicht mehr gewährt. Die Sperrung breitet sich über Keyrights übliche Client-Sperrlisten- und Kulanzfenster-Mechanik aus; der Webhook ist nur der Auslöser, kein neuer Durchsetzungspfad.

Vorbehalte und wann es bricht

Die Secret-Rotation braucht Überlappung. Wenn Sie das Signatur-Secret wechseln, akzeptieren Sie für eine Zeit beide Secrets: Probieren Sie zuerst das neue, dann das alte, bevor Sie ablehnen. Ein Verifizierer, der nur ein Secret kennt, macht aus jeder Rotation einen Ausfall.

Keine langsame Arbeit inline. Zahlungsanbieter erwarten ein schnelles 2xx und wiederholen, wenn Sie bei einer langen Datenbanktransaktion blockieren. Verifizieren, einreihen, quittieren – und dann außerhalb der Reihe abgleichen, über die Ereignis-id indexiert, damit Wiederholungen idempotent bleiben.

Ein Fehler für jedes Versagen. Geben Sie dasselbe 401 zurück, ob der Zeitstempel veraltet, die id fehlerhaft oder das HMAC falsch ist. Ein ausführlicher Fehler („falscher Zeitstempel“ gegen „falsche Signatur“) liefert einem Angreifer ein Sondier-Orakel.

Die Toleranz ist ein Kompromiss. Fünf Minuten verzeihen den üblichen Uhrenversatz zwischen Ihrem Server und dem Anbieter. Zu weit, und ein aufgezeichneter Webhook bleibt länger abspielbar, als ihn Ihr Cache merkt; zu eng, und legitime Zustellungen scheitern, wenn eine Uhr abdriftet. Synchronisieren Sie die Serveruhr per NTP und halten Sie das Fenster eng.

Fazit

Ein eingehender Webhook ist ein nicht vertrauenswürdiger POST, bis vier unabhängige Prüfungen bestehen: Das HMAC beweist, dass er von Ihrem Anbieter stammt, die Rohbytes beweisen, dass er nicht verändert wurde, der Zeitstempel beweist, dass er frisch ist, und der Replay-Cache beweist, dass er neu ist. Lassen Sie eine davon aus, und der leiseste Teil Ihres Lizenzsystems – der, der bei einer Rückerstattung sperrt – wird zum am leichtesten zu fälschenden. Verifizieren Sie über die tatsächlich signierten Bytes, vergleichen Sie in konstanter Zeit, und lassen Sie erst dann ein Billing-Ereignis eine Lizenz berühren.

Nebula.NET testen

Härten Sie Ihren .NET-Code in wenigen Minuten — starten Sie mit der kostenlosen Edition.