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

Ausgehende Lizenz-Event-Webhooks von Keyright

Hören Sie auf, die Lizenz-API abzufragen, um zu erfahren, was sich geändert hat. So pusht Keyright signierte Lifecycle-Events — aktiviert, widerrufen, erneuert, bald ablaufend — an Ihren eigenen Endpoint, und so verifizieren Sie die Signatur, überstehen At-least-once-Zustellung und weisen Replays auf der Empfängerseite ab.

Die meisten Teams erfahren, was ihr Lizenzsystem getan hat, indem sie es fragen. Ein nächtlicher Job holt die Liste der aktiven Lizenzen, vergleicht sie mit der von gestern und löst die E-Mails und CRM-Aktualisierungen aus, die Stunden früher hätten rausgehen sollen. Das funktioniert, bis es darauf ankommt: Ein Kunde erstattet um 9 Uhr zurück, Ihr „Aktive Kunden”-Dashboard zählt ihn um 17 Uhr noch mit, und eine Erneuerungserinnerung landet im Postfach von jemandem, der letzte Woche abgesprungen ist. Abfragen ist per Design immer veraltet, und je feiner Sie das Intervall schneiden, desto mehr hämmern Sie auf eine API ein, um meist zu erfahren, dass sich nichts geändert hat.

Die Lösung ist, den Fluss umzukehren. Statt dass Ihre Systeme den Ausstellungsdienst fragen, was sich geändert hat, sagt der Ausstellungsdienst Ihnen im Moment, in dem es sich ändert. Das tun Keyrights ausgehende Event-Webhooks: ein signierter HTTP-POST an einen Endpoint, den Sie besitzen, immer wenn eine Lizenz eine Grenze ihres Lifecycle überschreitet. Dieser Beitrag handelt davon, sie korrekt zu konsumieren — die Signatur, die Zustellgarantien und das Replay-Fenster — denn ein Webhook-Endpoint ist eine öffentliche Tür in Ihr Back-Office, und die drei Details, die ihn sicher machen, sind leicht falsch zu machen.

Wie ein Event aussieht

Jedes Event ist ein kleines JSON-Dokument mit einem stabilen Umschlag. Der type sagt Ihnen, was passiert ist; die data trägt die Lizenz, der es passiert ist. Die Umschlagfelder — id, type, created — sind über jedes Event gleich, sodass ein einziger Handler nach type routen und dem Rest der Form vertrauen kann.

{
  "id": "evt_01JD9Q4ZB2K7M3X8V0",
  "type": "license.revoked",
  "created": "2026-11-13T14:02:11Z",
  "data": {
    "licenseId": "lic_7c1f9a",
    "product": "acme-suite",
    "tier": "Pro",
    "customerRef": "cust_4821",
    "reason": "refund",
    "revokedAtUtc": "2026-11-13T14:02:10Z"
  }
}

Die Lifecycle-Events, die Sie tatsächlich verdrahten werden, sind eine kurze Liste:

  • license.activated — ein Schlüssel an ein neues Gerät oder einen Platz gebunden. Löst Provisionierung, Willkommens-E-Mail, Platzzahl-Synchronisation aus.
  • license.validated.new_node — eine bestehende Lizenz hat sich von einem Gerät eingecheckt, das sie nie zuvor genutzt hatte. Nützlich zur Missbrauchsüberwachung.
  • license.renewed — eine bezahlte Erneuerung hat den Ablauf verlängert. Aktualisieren Sie das „Bezahlt bis”-Datum in Ihrem CRM.
  • license.expiring — der Scheduler des Ausstellungsdienstes feuerte, weil eine Lizenz in ihrem Erneuerungsfenster liegt (sagen wir, 14 Tage vorher). Treibt die Mahnsequenz an.
  • license.revoked — ein Schlüssel wurde widerrufen (Erstattung, Rückbuchung, manuelle Aktion). Schalten Sie Feature Flags um, benachrichtigen Sie den Support.

Der Zustellweg

Ein Event wird in dem Moment erzeugt, in dem der Ausstellungsdienst die Zustandsänderung festschreibt, an einen Zustell-Worker übergeben und per POST an Ihre abonnierte URL gesendet. Ist Ihr Endpoint langsam, ausgefallen oder gibt ein Nicht-2xx zurück, wiederholt der Worker mit Backoff. Dieses Wiederholungsverhalten ist das Wichtigste, das es zu gestalten gilt, und das Diagramm macht die Konsequenz konkret: dasselbe Event kann mehr als einmal ankommen.

Ausstellungsdienst Zustell-Worker Ihr Endpoint festschreiben + einreihen POST + X-Keyright-Signature Timeout / 5xx Wiederholung (Backoff) — selbe event id 200 OK Zustellung bestätigt — Wiederholung stoppt

Das ist At-least-once-Zustellung, und es ist die richtige Garantie: Die Alternative — At-most-once — würde Events still verwerfen, sobald Ihr Endpoint stolpert, was schlimmer ist, als eines zweimal zu sehen. Ihre Aufgabe auf der Empfängerseite ist, ein Duplikat harmlos zu machen.

Detail 1 — die Signatur über den rohen Body verifizieren

Ihre Webhook-URL ist für jeden erreichbar, der sie erfährt. Handelt Ihr Handler nach dem, was er empfängt, kann jemand ein license.renewed für ein Konto POSTen, das nie bezahlt hat. Die Verteidigung ist ein HMAC, den der Ausstellungsdienst über die Payload mit einem Geheimnis berechnet, das nur Sie beide halten, gesendet in X-Keyright-Signature neben einem X-Keyright-Timestamp. Die signierte Zeichenkette ist der Zeitstempel und der rohe Body, durch einen Punkt verbunden — was die Signatur ebenso an einen Zeitpunkt wie an die Bytes bindet.

Die Falle, die jeden erwischt: Verifizieren Sie über die exakten rohen Bytes, die Sie empfangen haben, bevor Sie irgendetwas deserialisieren. Model Binding reserialisiert das JSON mit anderem Whitespace und anderer Schlüsselreihenfolge, und der neu berechnete HMAC wird nie übereinstimmen. Lesen Sie den Body einmal als String, verifizieren Sie, dann parsen Sie.

app.MapPost("/webhooks/keyright", async (HttpRequest req) =>
{
    using var reader = new StreamReader(req.Body);
    string rawBody = await reader.ReadToEndAsync();   // die exakten Bytes, unberührt

    string signature = req.Headers["X-Keyright-Signature"];
    string timestamp = req.Headers["X-Keyright-Timestamp"];

    if (!WebhookVerifier.IsValid(rawBody, timestamp, signature, Secret))
        return Results.Unauthorized();

    var evt = JsonSerializer.Deserialize<WebhookEvent>(rawBody)!;  // jetzt sicher zu parsen
    await _dispatcher.HandleAsync(evt);
    return Results.Ok();
});

Der Verifizierer berechnet den HMAC neu und vergleicht in konstanter Zeit — ein einfaches == auf den Hex-Zeichenketten verrät über die benötigte Zeit, wie viele führende Bytes übereinstimmten, was genügt, um eine Signatur Byte für Byte zu fälschen. CryptographicOperations.FixedTimeEquals schließt diese Tür.

public static class WebhookVerifier
{
    public static bool IsValid(string body, string timestamp, string header, byte[] secret)
    {
        // Alles älter als fünf Minuten ablehnen: verkleinert das Replay-Fenster.
        if (!long.TryParse(timestamp, out var unix)) return false;
        var age = DateTimeOffset.UtcNow - DateTimeOffset.FromUnixTimeSeconds(unix);
        if (age > TimeSpan.FromMinutes(5) || age < TimeSpan.FromMinutes(-5)) return false;

        var signed = Encoding.UTF8.GetBytes($"{timestamp}.{body}");
        var expected = HMACSHA256.HashData(secret, signed);

        Span<byte> provided = stackalloc byte[32];
        if (!Convert.TryFromHexString(header, provided, out int n) || n != 32) return false;

        return CryptographicOperations.FixedTimeEquals(expected, provided);
    }
}

Detail 2 — den Konsumenten idempotent machen

Da die Zustellung At-least-once ist, muss Ihr Handler dasselbe Ergebnis liefern, ob er ein Event einmal oder fünfmal sieht. Schlüsseln Sie Ihre Verarbeitung auf die id des Umschlags, die über Wiederholungen desselben Events stabil ist, und erfassen Sie sie, sobald Sie zum ersten Mal handeln. Eine zweite Ankunft findet den Eintrag und kehrt früh zurück.

public async Task HandleAsync(WebhookEvent evt)
{
    // INSERT ... ON CONFLICT DO NOTHING auf der event id; 0 Zeilen = schon gesehen.
    if (!await _events.TryClaimAsync(evt.Id))
        return;                                   // Duplikat — schon verarbeitet, bestätigen

    switch (evt.Type)
    {
        case "license.revoked":  await _crm.MarkChurnedAsync(evt.Data.CustomerRef); break;
        case "license.renewed":  await _crm.ExtendPaidThroughAsync(evt.Data); break;
        case "license.expiring": await _dunning.StartAsync(evt.Data); break;
        // ignorieren Sie nicht behandelte Event-Typen — kein 4xx, nur bestätigen
    }
}

Beachten Sie den letzten Kommentar. Geben Sie 2xx für Events zurück, die Sie nicht interessieren. Ein 4xx sagt dem Ausstellungsdienst, die Zustellung sei fehlgeschlagen, also wiederholt er weiter ein Event, das Sie nie nutzen wollten, und Ihre Wiederholungs-Warteschlange staut sich dahinter.

Schnell antworten, später arbeiten

Der Zustell-Worker hat ein Timeout. Erledigt Ihr Handler echte Arbeit — E-Mail senden, ein CRM aufrufen — innerhalb der Anfrage, wird eine langsame Abhängigkeit zu einem Webhook-Timeout und einer unnötigen Wiederholung. Für alles jenseits eines schnellen Schreibvorgangs beanspruchen Sie die event id, reihen Sie die Arbeit in Ihren eigenen Hintergrundprozessor ein und geben Sie sofort 200 zurück. Sie haben den Empfang bestätigt; die Verarbeitung ist nun Ihr Problem, nicht das des Ausstellungsdienstes.

Ein Abonnement konfigurieren

Abonnements werden über die Keyright-CLI gegen Ihre selbstgehostete Instanz verwaltet. Erstellen Sie eines mit der Ziel-URL und den gewünschten Event-Typen; der Befehl gibt das Signaturgeheimnis einmalig zurück, das Sie dort speichern, wo Ihre App ihre Geheimnisse liest.

keyright webhooks create \
  --url https://api.acme.example/webhooks/keyright \
  --events license.activated,license.renewed,license.revoked,license.expiring \
  --product acme-suite
# -> Endpoint whk_4f91, Signaturgeheimnis whsec_... (einmalig angezeigt)

Abonnieren Sie nur die Events, die Sie behandeln. Ein engeres Abonnement bedeutet weniger Traffic, eine kleinere Angriffsfläche und einen klareren Vertrag für den nächsten Ingenieur, der Ihren Handler liest.

Webhooks benachrichtigen; das SDK setzt durch

Eine Grenze ist es wert, klar benannt zu werden, denn sie zu verwechseln verursacht echte Ausfälle. Webhooks sind für Ihre Back-Office-Systeme — CRM, E-Mail, Dashboards, Provisionierung. Sie sind nicht, wie die lizenzierte Anwendung entscheidet, ob sie läuft. Diese Entscheidung bleibt in der App, die das Keyright-SDK mit ihrem Produkt und öffentlichen Schlüssel initialisiert und Validate gegen die signierte Lizenz aufruft, die sie hält, und Funktionen fail-closed sperrt.

var keyright = new KeyrightClient(product: "acme-suite", publicKey: EmbeddedKey);
var info = await keyright.ValidateAsync();
if (!info.IsValid || !info.Entitlements.Has("export"))
    throw new FeatureLockedException("export");   // fail closed, lokal, jedes Mal

Halten Sie die beiden Anliegen getrennt, und beide werden einfacher. Ein durch einen Wiederholungssturm verzögerter Webhook kann immer noch keine App ohne Lizenz laufen lassen, weil die App dem Webhook von vornherein nie vertraut hat. Und eine Lizenzprüfung, die offline fehlschlägt, funktioniert trotzdem, weil sie nicht davon abhängt, dass Ihr CRM von der Nachricht erfahren hat. Der Webhook ist, wie Ihr Unternehmen eine Lizenzänderung in Echtzeit erfährt; die signierte Lizenz und das SDK-Gate sind, wie Ihre Software sie durchsetzt.

Nebula.NET testen

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