Schlüssel automatisch aus einem Shop ausstellen

Ziel. Ein Kunde bezahlt in Ihrem Shop (oder bei einem Merchant-of-Record, der in Ihrem Namen verkauft), und eine Keyright-Lizenz wird ohne manuellen Schritt erzeugt und ihm per E-Mail zugestellt — und eine Rückerstattung oder Kündigung widerruft sie genauso automatisch.

Wann einsetzen

• Nutzen Sie dies, wenn Sie über einen Checkout verkaufen — Ihren eigenen Shop, einen Zahlungsanbieter oder einen Merchant-of-Record (MoR), der Steuern und Abrechnung übernimmt — und die Bestellabwicklung ohne Handarbeit ablaufen soll.
• Nutzen Sie dies, wenn Rückerstattungen und Kündigungen den Zugang beenden sollen, ohne dass jemand an den Widerruf denken muss.
• Nicht nutzen, wenn Sie Schlüssel von Hand an eine Handvoll Enterprise-Kunden ausstellen (nutzen Sie einfach Licenses → Issue license oder POST /admin/licenses) oder wenn Ihr Abrechnungssystem die Admin-API bereits selbst aufruft — der Webhook ist eine Bequemlichkeit, nicht der einzige Weg.

Dies ist in erster Linie eine Bequemlichkeit für die Cloud — der gehostete Service ist bereits aus dem öffentlichen Internet erreichbar, sodass ein Shop direkt dorthin POSTen kann. Es funktioniert auch bei Self-Hosting, solange Ihre Instanz für den Shop erreichbar ist (eine öffentliche URL oder ein Tunnel, den der Anbieter ansprechen kann); alles Folgende ist bis auf die Basis-URL identisch.

Was Sie tun (Anbieterseite)

1. Webhook-URL und Secret beschaffen

Jeder Mandant hat einen mandantenspezifischen Fulfillment-Webhook unter POST /webhooks/fulfill/{slug} (wobei {slug} Ihr Mandant ist) sowie ein Secret, mit dem Events per HMAC signiert werden. Der Mandant wird aus der Route übernommen und dem Event aufgezwungen, sodass eine für einen Mandanten gültige Signatur nie eine Lizenz in einem anderen erzeugen kann.

Beides finden Sie in den Integrations-/Entwicklereinstellungen des Dashboards oder über die API: GET /admin/account liefert einen integration-Block mit der Basis-URL, dem öffentlichen Signaturschlüssel und der Webhook-URL. Das Secret können Sie jederzeit rotieren (Owner-Rolle):

curl -X POST $BASE/admin/webhook-secret/rotate -H "X-Admin-Token: $TOKEN"
# -> { "webhookSecret": "…", "webhookUrl": "https://keyright.delta1labs.com/webhooks/fulfill/acme" }

2. Ihren Shop darauf ausrichten

Fügen Sie in Ihrem Shop / Zahlungsanbieter / MoR einen Webhook hinzu, der im Bestell-Lebenszyklus ausgelöst wird, und setzen Sie:

• URL — Ihr /webhooks/fulfill/{slug}.
• Signatur-Secret — das webhookSecret von oben. Der Anbieter signiert den rohen Request-Body per HMAC und sendet die Signatur im Header X-Keyright-Signature; Keyright verifiziert sie mit Ihrem Secret und weist alles zurück, was nicht übereinstimmt (401).

Die meisten Shops senden ihr eigenes Event-Format. Keyright erwartet ein normalisiertes Event; weicht die Nutzlast Ihres Anbieters davon ab, schalten Sie einen schlanken Adapter davor (eine kleine Funktion, die den Webhook des Anbieters in den normalisierten Body übersetzt, ihn signiert und weiterleitet). Der normalisierte Body:

{
  "type": "paid",
  "licensee": "Acme Inc.",
  "product": "acme-app",
  "tier": "pro",
  "seats": 3,
  "expiryUtc": "2027-10-12T00:00:00Z",
  "orderRef": "order_8421",
  "email": "buyer@acme.com"
}

• type bestimmt die Aktion: Ein paid-Event (paid / order.paid / issue) erzeugt eine Lizenz; ein refund- / cancel- / revoke-Event widerruft sie.
• product und tier sind die Mittel, mit denen Sie Produkt/Variante des Shops einem Keyright-Produkt + einer Edition zuordnen. Ihr Shop verkauft eine SKU; Sie entscheiden, welchem Keyright-product-Slug und welchem tier (Edition) diese SKU entspricht, und setzen diese Felder im Event (direkt oder in der Zuordnungstabelle Ihres Adapters). Die Plätze, Entitlements und eine etwaige Abdeckungsrichtlinie der Edition werden bei der Ausstellung automatisch angewendet, genau wie bei einer von Hand ausgestellten Lizenz — ein über den Shop ausgestellter Pro-Schlüssel ist also nicht von einem im Dashboard ausgestellten zu unterscheiden.
• seats / expiryUtc überschreiben die Standardwerte der Edition, wenn die SKU es verlangt (z. B. ein 5-Platz-Paket oder eine Jahreslaufzeit).
• orderRef ist der Idempotenz-Anker (nächster Abschnitt) — senden Sie immer die Bestell-ID Ihres Shops.
• email ist die Adresse, an die der Schlüssel gesendet wird.

Ein tenant-Feld im Body wird auf der mandantenspezifischen Route ignoriert — der Slug in der URL gewinnt immer.

3. Was der Kunde erhält

Bei einem paid-Event erzeugt Keyright die Lizenz und sendet den Schlüssel per E-Mail an email (damit die Mail hinausgeht, muss auf der Instanz SMTP konfiguriert sein). Der Käufer fügt diesen Schlüssel in Ihre Anwendung ein und aktiviert ihn wie jede andere Lizenz — siehe Erste Schritte. Weder Aktivierung noch Plätze noch Entitlements unterscheiden sich, nur weil der Schlüssel aus einem Shop stammt.

Idempotenz & Wiederholungen

Shops wiederholen Webhooks — bei einem Timeout, einem 5xx oder einem Aussetzer des Anbieters erhalten Sie dasselbe Event mehr als einmal. Keyright macht paid idempotent pro orderRef: Die erste Zustellung erzeugt die Lizenz, und jede spätere Zustellung mit derselben orderRef liefert die bestehende Lizenz zurück, statt einen zweiten Schlüssel auszustellen. Deshalb muss orderRef stabil sein (die Bestell-ID Ihres Shops, keine ID pro Zustellversuch). Der Endpunkt antwortet bei jedem behandelten Ergebnis mit 200 — ausgestellt, existiert bereits, widerrufen oder ignoriert —, sodass ein wohlerzogener Shop Erfolg sieht und die Wiederholungen einstellt.

Rückerstattungs-/Kündigungs-Events widerrufen die Lizenz, die diese Bestellung erzeugt hat; die Anwendung des Kunden fällt bei der nächsten Lease-Aktualisierung auf Free zurück (siehe Widerrufen, verlängern & Ablauf behandeln). Eine Rückerstattung für eine Bestellung, die nie abgewickelt wurde, ist ein No-op (ignoriert, trotzdem 200).

In Ihrem Code

Für die Bestellabwicklung gibt es keine SDK-Arbeit auf Anwendungsseite — es ist ein Server-zu-Server-Ablauf zwischen Ihrem Shop und Keyright, und die Anwendung des Kunden sieht immer nur einen gewöhnlichen Lizenzschlüssel. Der einzige Code, den Sie möglicherweise schreiben, ist der optionale Adapter, der den Webhook Ihres Anbieters normalisiert. Skizze:

// Minimaler Adapter: ein Anbieter-Event in den normalisierten, HMAC-signierten Body von Keyright übersetzen.
var evt = new {
    type     = providerEvent.IsPaid ? "paid" : "refund",
    licensee = providerEvent.CustomerName,
    product  = MapToKeyrightProduct(providerEvent.Sku),   // Ihre SKU → Keyright-Produkt-Slug
    tier     = MapToKeyrightTier(providerEvent.Sku),      // Ihre SKU → Edition
    seats    = providerEvent.Quantity,
    orderRef = providerEvent.OrderId,                     // der Idempotenz-Anker
    email    = providerEvent.CustomerEmail,
};
var body = JsonSerializer.SerializeToUtf8Bytes(evt);
var sig  = Convert.ToBase64String(new HMACSHA256(secretBytes).ComputeHash(body));   // über die ROHEN Bytes
using var http = new HttpClient();
var req = new HttpRequestMessage(HttpMethod.Post, "https://keyright.delta1labs.com/webhooks/fulfill/acme")
    { Content = new ByteArrayContent(body) };
req.Content.Headers.ContentType = new("application/json");
req.Headers.Add("X-Keyright-Signature", sig);
await http.SendAsync(req);

Wenn Ihr Anbieter direkt einen eigenen JSON-Body und ein eigenes Signaturschema senden kann (manche können das), brauchen Sie unter Umständen gar keinen Adapter — richten Sie ihn mit dem oben gezeigten normalisierten Format direkt auf den Webhook aus.

Cloud vs. Self-Hosting

• Erreichbarkeit ist der einzige echte Unterschied: Die Cloud ist öffentlich, ein Shop erreicht https://keyright.delta1labs.com/webhooks/fulfill/{slug} also von Haus aus; eine selbst gehostete Instanz muss für den Shop unter einer URL erreichbar sein, an die er POSTen kann.
• Die alte Single-Tenant-Route. Eine selbst gehostete Instanz mit einem einzigen Mandanten kann stattdessen das deploymentweite POST /webhooks/fulfill mit einem KEYRIGHT_WEBHOOK_SECRET verwenden. Bevorzugen Sie die mandantenspezifische Route /webhooks/fulfill/{slug}, sobald die Instanz mehr als einen Mandanten hat.
• $BASE / $TOKEN / SMTP folgen der üblichen Aufteilung; der E-Mail-Versand des Schlüssels erfordert konfigurierten Mailversand auf derjenigen Instanz, die die Lizenz erzeugt.

Prüfen

1. Rotieren Sie das Webhook-Secret und notieren Sie es; ordnen Sie eine Shop-SKU product=acme-app, tier=pro zu.
2. Senden Sie ein Test-paid-Event mit einer echten email und einer frischen orderRef, signiert mit dem Secret. Erwartet: 200, eine neue Lizenz unter Licenses und der Schlüssel im Posteingang.
3. Idempotenz: Senden Sie exakt dasselbe Event erneut. Erwartet: 200 und keine zweite Lizenz — derselbe Schlüssel kommt zurück.
4. Falsche Signatur: Senden Sie denselben Body mit einer falschen Signatur. Erwartet: 401 und keine Lizenz.
5. Rückerstattung: Senden Sie ein refund-Event für diese orderRef. Die Lizenz wechselt auf widerrufen; die Anwendung des Kunden fällt bei der nächsten Aktualisierung auf Free zurück.

Siehe auch

• Erste Schritte — die Einrichtung auf Anbieterseite und was der Käufer mit dem Schlüssel macht.
• Widerrufen, verlängern & Ablauf behandeln — was ein durch Rückerstattung ausgelöster Widerruf mit einer laufenden Anwendung macht.
• Funktionen & Editionen steuern — die Entitlements, die eine über den Shop ausgestellte Edition trägt.
• HTTP-API-Referenz — die Webhook- und Admin-Endpunkte im Detail.