Vérifier les webhooks de facturation entrants en .NET
Votre serveur de licences fait confiance à un POST de votre prestataire de paiement, jusqu'à ce qu'un attaquant envoie le sien. Comment vérifier correctement les webhooks entrants signés par HMAC : signature sur les octets bruts, comparaison à temps constant, tolérance d'horodatage et défense anti-rejeu, puis réconcilier un remboursement avec la révocation de la licence.
Un serveur de licences ne vaut que les événements auxquels il réagit. Lorsqu’un client est remboursé, votre prestataire de paiement envoie un webhook ; votre back-end révoque la licence ; la vérification suivante échoue en mode fermé. Toute la chaîne repose sur une hypothèse : que le POST provient réellement du prestataire. Retirez-la et quiconque découvre l’URL du point de terminaison peut révoquer la licence d’un concurrent, ou s’octroyer une licence perpétuelle, avec un seul curl.
Les prestataires résolvent cela en signant chaque webhook avec un secret partagé. La signature ne vaut que ce que vaut votre vérification, et c’est là que la plupart des intégrations échouent en silence.
La vraie question
Que vérifiez-vous exactement, et par rapport à quoi ? Un gestionnaire naïf se rabat sur le corps déjà analysé et une comparaison de chaînes :
// 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();
});
Chaque ligne ici est une faille. Le corps a été resérialisé, donc les octets ne correspondent plus à ce qui a été signé. La comparaison est ==, qui fuit la temporisation. Et rien n’empêche un attaquant de capturer un webhook réel et de le rejouer mille fois. Corrigeons les trois.
Le contenu signé
Un prestataire typique envoie un en-tête qui porte à la fois un horodatage et une ou plusieurs signatures :
X-Keyright-Signature: t=1763305200,v1=4f2d...e9 (64 hex chars)
La signature v1 est HMAC-SHA256(secret, signedContent), et le contenu signé n’est pas le corps seul : c’est l’horodatage, un séparateur et les octets bruts du corps concaténés :
signedContent = "1763305200" + "." + <raw request body bytes>
Inclure l’horodatage dans le HMAC est ce qui rend la défense anti-rejeu possible : vous ne pouvez pas conserver la signature et mentir sur le moment de son émission, car l’heure fait partie de ce qui a été signé.
Le vérificateur
Voici un vérificateur correct. Il analyse l’en-tête, applique la fenêtre temporelle, recalcule le HMAC sur le contenu signé exact et compare en temps constant.
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
}
}
Trois détails portent la sécurité. HMACSHA256.HashData utilise le secret partagé comme clé du hachage, donc seul celui qui le détient peut produire un condensé correspondant. FixedTimeEquals compare les 32 octets quel que soit l’endroit de la première divergence, donc aucun oracle de temporisation ne fuit. Et l’horodatage est à l’intérieur de signed, donc il ne peut être modifié sans invalider v1.
Capturer les octets exacts
Le vérificateur est inutile si vous lui passez les mauvais octets. Dans ASP.NET Core, dès que vous liez un modèle, le framework lit et jette le flux de la requête, et même si vous resérialisez l’objet analysé vous obtenez des octets différents de ceux signés par le prestataire. Lisez d’abord le corps brut :
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();
});
Ce n’est qu’après la vérification qu’il est sûr de désérialiser. Le cache anti-rejeu stocke chaque id d’événement avec un TTL qui dépasse confortablement l’horizon de réessais du prestataire ; une seconde livraison du même id est confirmée par 200 mais ne fait rien. Renvoyer 200 plutôt qu’une erreur est délibéré : l’événement a été traité, vous ne voulez donc pas que le prestataire continue de réessayer.
Réconcilier avec l’état de la licence
Avec un événement fiable en main, la correspondance vers Keyright est modeste. Un remboursement ou un litige révoquent ; un renouvellement réussi prolonge. Gardez le switch étroit et échouez en mode fermé sur tout ce qui est inattendu :
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
};
Une fois révoquée, la vérification suivante du SDK échoue en mode fermé et les droits du client — un ensemble choisi par le prestataire, tel que max_projects, feature.export ou max_major_version — cessent d’être accordés. La révocation se propage via la machinerie habituelle de liste de blocage côté client et de fenêtre de grâce de Keyright ; le webhook n’est que le déclencheur, pas une nouvelle voie d’application.
Mises en garde et cas de rupture
La rotation du secret exige un chevauchement. Lorsque vous changez le secret de signature, acceptez l’un ou l’autre secret pendant une période : essayez d’abord le nouveau, puis l’ancien, avant de rejeter. Un vérificateur qui ne connaît qu’un seul secret transforme chaque rotation en panne.
Ne faites pas de travail lent en ligne. Les prestataires de paiement attendent un 2xx rapide et réessaient si vous bloquez sur une longue transaction de base de données. Vérifiez, mettez en file, confirmez, puis réconciliez hors bande, indexé sur l’id de l’événement pour que les réessais restent idempotents.
Une seule erreur pour chaque échec. Renvoyez le même 401 que l’horodatage soit périmé, que l’id soit malformé ou que le HMAC soit incorrect. Une erreur détaillée (« horodatage incorrect » contre « signature incorrecte ») offre à un attaquant un oracle de sondage.
La tolérance est un compromis. Cinq minutes pardonnent le décalage d’horloge habituel entre votre serveur et le prestataire. Trop large et un webhook capturé reste rejouable plus longtemps que votre cache ne le mémorise ; trop étroite et des livraisons légitimes échouent quand une horloge dérive. Synchronisez l’horloge de votre serveur avec NTP et gardez la fenêtre serrée.
À retenir
Un webhook entrant est un POST non fiable jusqu’à ce que quatre contrôles indépendants passent : le HMAC prouve qu’il vient de votre prestataire, les octets bruts prouvent qu’il n’a pas été altéré, l’horodatage prouve qu’il est frais et le cache anti-rejeu prouve qu’il est nouveau. Négligez-en un et la partie la plus silencieuse de votre système de licences — celle qui révoque sur un remboursement — devient la plus facile à forger. Vérifiez sur les octets réellement signés, comparez en temps constant, et ce n’est qu’alors que vous laissez un événement de facturation toucher une licence.
Essayez Nebula.NET
Renforcez votre code .NET en quelques minutes — commencez avec l'édition gratuite.