Skip to content
← Tous les articles
· Delta1 Labs WebhooksKeyright

Webhooks d'événements de licence sortants de Keyright

Arrêtez d'interroger l'API de licences pour savoir ce qui a changé. Voici comment Keyright pousse des événements de cycle de vie signés — activée, révoquée, renouvelée, bientôt expirée — vers votre propre endpoint, et comment vérifier la signature, survivre à la livraison au-moins-une-fois et rejeter les rejeux côté réception.

La plupart des équipes apprennent ce qu”a fait leur système de licences en le lui demandant. Une tâche nocturne récupère la liste des licences actives, la compare à celle d”hier et déclenche les e-mails et mises à jour CRM qui auraient dû partir des heures plus tôt. Ça marche jusqu”à ce que ça compte : un client se fait rembourser à 9h, votre tableau de bord « clients actifs » le compte encore à 17h, et un rappel de renouvellement atterrit dans la boîte de quelqu”un parti la semaine dernière. L”interrogation est toujours périmée par conception, et plus vous affinez l”intervalle, plus vous martelez une API pour, le plus souvent, apprendre que rien n”a changé.

La solution est d”inverser le flux. Au lieu que vos systèmes demandent au service émetteur ce qui a changé, le service émetteur vous prévient au moment où ça change. C”est ce que font les webhooks d”événements sortants de Keyright : un POST HTTP signé vers un endpoint que vous possédez, chaque fois qu”une licence franchit une limite de son cycle de vie. Cet article porte sur leur consommation correcte — la signature, les garanties de livraison et la fenêtre de rejeu — car un endpoint de webhook est une porte publique vers votre back-office, et les trois détails qui le rendent sûr sont faciles à rater.

À quoi ressemble un événement

Chaque événement est un petit document JSON avec une enveloppe stable. Le type vous dit ce qui s”est passé ; le data porte la licence concernée. Les champs de l”enveloppe — id, type, created — sont les mêmes pour tous les événements, de sorte qu”un seul handler peut router sur type et faire confiance au reste de la forme.

{
  "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"
  }
}

Les événements de cycle de vie que vous câblerez réellement forment une courte liste :

  • license.activated — une clé liée à un nouvel appareil ou siège. Déclenche le provisionnement, l”e-mail de bienvenue, la synchronisation du nombre de sièges.
  • license.validated.new_node — une licence existante s”est enregistrée depuis un appareil jamais utilisé auparavant. Utile pour la surveillance des abus.
  • license.renewed — un renouvellement payé a prolongé l”expiration. Mettez à jour la date « payé jusqu”au » dans votre CRM.
  • license.expiring — le planificateur du service émetteur s”est déclenché parce qu”une licence est dans sa fenêtre de renouvellement (disons, à 14 jours). Pilotez la séquence de relance.
  • license.revoked — une clé a été révoquée (remboursement, rétrofacturation, action manuelle). Basculez les feature flags, prévenez le support.

Le chemin de livraison

Un événement est produit à l”instant où le service émetteur valide le changement d”état, remis à un worker de livraison et envoyé par POST à votre URL abonnée. Si votre endpoint est lent, en panne ou renvoie un non-2xx, le worker réessaie avec backoff. Ce comportement de réessai est la chose la plus importante à concevoir, et le diagramme rend la conséquence concrète : le même événement peut arriver plus d”une fois.

Service émetteur Worker de livraison Votre endpoint valide + met en file POST + X-Keyright-Signature timeout / 5xx réessai (backoff) — même event id 200 OK livraison confirmée — arrêt des réessais

C”est une livraison au-moins-une-fois, et c”est la bonne garantie : l”alternative — au-plus-une-fois — abandonnerait silencieusement des événements chaque fois que votre endpoint trébuche, ce qui est pire que d”en voir un deux fois. Votre travail côté réception est de rendre un doublon inoffensif.

Détail 1 — vérifier la signature sur le corps brut

Votre URL de webhook est joignable par quiconque la découvre. Si votre handler agit sur ce qu”il reçoit, quelqu”un peut faire un POST d”un license.renewed pour un compte qui n”a jamais payé. La défense est un HMAC que le service émetteur calcule sur le payload avec un secret que vous êtes seuls à détenir, envoyé dans X-Keyright-Signature à côté d”un X-Keyright-Timestamp. La chaîne signée est l”horodatage et le corps brut joints par un point — ce qui lie la signature à un instant dans le temps autant qu”aux octets.

Le piège qui attrape tout le monde : vérifiez sur les octets bruts exacts reçus, avant toute désérialisation. Le model binding resérialise le JSON avec un autre espacement et un autre ordre de clés, et le HMAC recalculé ne correspondra jamais. Lisez le corps en chaîne une fois, vérifiez, puis analysez.

app.MapPost("/webhooks/keyright", async (HttpRequest req) =>
{
    using var reader = new StreamReader(req.Body);
    string rawBody = await reader.ReadToEndAsync();   // les octets exacts, intacts

    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)!;  // analyse sûre maintenant
    await _dispatcher.HandleAsync(evt);
    return Results.Ok();
});

Le vérificateur recalcule le HMAC et compare en temps constant — un simple == sur les chaînes hex fuit, par le temps qu”il prend, combien d”octets de tête ont coïncidé, ce qui suffit à forger une signature octet par octet. CryptographicOperations.FixedTimeEquals ferme cette porte.

public static class WebhookVerifier
{
    public static bool IsValid(string body, string timestamp, string header, byte[] secret)
    {
        // Rejette tout ce qui dépasse cinq minutes : réduit la fenêtre de rejeu.
        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);
    }
}

Détail 2 — rendre le consommateur idempotent

Comme la livraison est au-moins-une-fois, votre handler doit produire le même résultat qu”il voie un événement une fois ou cinq. Prenez pour clé de votre traitement l”id de l”enveloppe, qui est stable entre les réessais du même événement, et enregistrez-le la première fois que vous agissez. Une seconde arrivée trouve l”enregistrement et retourne tôt.

public async Task HandleAsync(WebhookEvent evt)
{
    // INSERT ... ON CONFLICT DO NOTHING sur l''event id ; 0 ligne = déjà vu.
    if (!await _events.TryClaimAsync(evt.Id))
        return;                                   // doublon — déjà traité, on confirme

    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;
        // ignorez les types d''événements non gérés — pas de 4xx, confirmez simplement
    }
}

Notez le dernier commentaire. Renvoyez 2xx pour les événements qui ne vous intéressent pas. Un 4xx dit au service émetteur que la livraison a échoué, donc il continuera à réessayer un événement que vous n”alliez jamais utiliser, et votre file de réessais s”engorge derrière lui.

Répondez vite, travaillez après

Le worker de livraison a un timeout. Si votre handler fait un vrai travail — envoyer un e-mail, appeler un CRM — dans la requête, une dépendance lente se transforme en timeout de webhook et en réessai inutile. Pour tout ce qui dépasse une écriture rapide, réclamez l”event id, mettez le travail en file vers votre propre processeur en arrière-plan et renvoyez 200 immédiatement. Vous avez confirmé la réception ; le traitement est désormais votre problème, pas celui du service émetteur.

Configurer un abonnement

Les abonnements se gèrent via la CLI Keyright contre votre instance auto-hébergée. Créez-en un avec l”URL de destination et les types d”événements souhaités ; la commande renvoie le secret de signature une seule fois, que vous stockez là où votre application lit ses secrets.

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, secret de signature whsec_... (affiché une fois)

Abonnez-vous uniquement aux événements que vous gérez. Un abonnement plus étroit, c”est moins de trafic, une surface d”attaque plus petite et un contrat plus clair pour le prochain ingénieur qui lira votre handler.

Les webhooks notifient ; le SDK applique

Une frontière mérite d”être énoncée clairement, car la confondre provoque de vraies pannes. Les webhooks sont pour vos systèmes de back-office — CRM, e-mails, tableaux de bord, provisionnement. Ce n”est pas ainsi que l”application sous licence décide de s”exécuter. Cette décision reste dans l”application, qui initialise le SDK Keyright avec son produit et sa clé publique et appelle Validate contre la licence signée qu”elle détient, verrouillant les fonctionnalités en fail-closed.

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, en local, à chaque fois

Gardez les deux préoccupations séparées et toutes deux se simplifient. Un webhook retardé par une tempête de réessais ne peut toujours pas laisser s”exécuter une application sans licence, parce que l”application n”a jamais fait confiance au webhook au départ. Et une vérification de licence qui échoue hors ligne fonctionne toujours, parce qu”elle ne dépend pas de ce que votre CRM ait eu vent de la nouvelle. Le webhook, c”est la façon dont votre entreprise apprend un changement de licence en temps réel ; la licence signée et le gate du SDK, c”est la façon dont votre logiciel l”applique.

Essayez Nebula.NET

Renforcez votre code .NET en quelques minutes — commencez avec l'édition gratuite.