Skip to content
← Todas las publicaciones
· Delta1 Labs WebhooksKeyright

Verificar webhooks de facturación entrantes en .NET

Tu servidor de licencias confía en un POST de tu proveedor de pagos, hasta que un atacante envía el suyo. Cómo verificar correctamente webhooks entrantes firmados con HMAC: firma sobre los bytes crudos, comparación en tiempo constante, tolerancia de marca de tiempo y defensa contra repetición, y luego reconciliar un reembolso con la revocación de la licencia.

Un servidor de licencias solo es tan fiable como los eventos a los que reacciona. Cuando se reembolsa a un cliente, tu proveedor de pagos envía un webhook; tu back-end revoca la licencia; la siguiente verificación falla cerrada. Toda la cadena depende de una suposición: que el POST realmente vino del proveedor. Quítala y cualquiera que descubra la URL del endpoint puede revocar la licencia de un competidor, o concederse a sí mismo una perpetua, con un solo curl.

Los proveedores resuelven esto firmando cada webhook con un secreto compartido. La firma solo es tan buena como tu verificación de ella, y esa verificación es donde la mayoría de las integraciones fallan silenciosamente.

La verdadera pregunta

¿Qué estás verificando exactamente, y contra qué? Un manejador ingenuo recurre al cuerpo ya analizado y a una comparación de cadenas:

// 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();
});

Cada línea aquí es un agujero. El cuerpo se volvió a serializar, así que los bytes ya no coinciden con lo que se firmó. La comparación es ==, que filtra temporización. Y nada impide que un atacante capture un webhook real y lo repita mil veces. Arreglemos las tres cosas.

El contenido firmado

Un proveedor típico envía una cabecera que lleva tanto una marca de tiempo como una o más firmas:

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

La firma v1 es HMAC-SHA256(secret, signedContent), y el contenido firmado no es solo el cuerpo: es la marca de tiempo, un separador y los bytes crudos del cuerpo concatenados:

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

Incluir la marca de tiempo dentro del HMAC es lo que hace posible la defensa contra repetición: no puedes conservar la firma y mentir sobre cuándo se emitió, porque el tiempo forma parte de lo que se firmó.

Bytes crudos antes del binding t . body contenido firmado HMAC-SHA256 con el secreto FixedTimeEquals esperado vs v1 Ventana temporal rechazar si |now - t| > 5m Caché de repetición rechazar id ya visto Aceptar reconciliar licencia 401 Unauthorized si falla una puerta
Cuatro puertas independientes. Autenticidad (HMAC), integridad (los mismos bytes crudos), frescura (ventana temporal) y unicidad (caché de repetición) deben pasar todas antes de que un evento de facturación toque el estado de la licencia.

El verificador

Aquí tienes un verificador correcto. Analiza la cabecera, aplica la ventana temporal, recalcula el HMAC sobre el contenido firmado exacto y compara en tiempo constante.

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

Tres detalles sostienen la seguridad. HMACSHA256.HashData aplica el secreto compartido como clave del hash, así que solo quien lo posee puede producir un resumen coincidente. FixedTimeEquals compara los 32 bytes sin importar dónde difieran por primera vez, así que no se filtra ningún oráculo de temporización. Y la marca de tiempo está dentro de signed, así que no puede alterarse sin invalidar v1.

Capturar los bytes exactos

El verificador es inútil si le pasas los bytes equivocados. En ASP.NET Core, en cuanto enlazas un modelo el framework lee y descarta el flujo de la petición, e incluso si vuelves a serializar el objeto analizado obtienes bytes diferentes de los que firmó el proveedor. Lee primero el cuerpo crudo:

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();
});

Solo después de la verificación es seguro deserializar. La caché de repetición almacena cada id de evento con un TTL que supera cómodamente el horizonte de reintentos del proveedor; una segunda entrega del mismo id se confirma con 200 pero no hace nada. Devolver 200 en lugar de un error es deliberado: el evento se gestionó, así que no quieres que el proveedor siga reintentando.

Reconciliar con el estado de la licencia

Con un evento fiable en la mano, el mapeo a Keyright es pequeño. Un reembolso o una disputa revocan; una renovación con éxito extiende. Mantén el switch estrecho y falla cerrado ante cualquier cosa inesperada:

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
    };

Una vez revocada, la siguiente verificación del SDK falla cerrada y los derechos del cliente —un conjunto elegido por el proveedor, como max_projects, feature.export o max_major_version— dejan de concederse. La revocación se propaga por la maquinaria normal de lista de bloqueo del cliente y ventana de gracia de Keyright; el webhook es solo el disparador, no una nueva vía de aplicación.

Advertencias y cuándo se rompe

La rotación del secreto necesita solapamiento. Cuando rotes el secreto de firma, acepta cualquiera de los dos secretos durante un periodo: prueba primero el nuevo, luego el antiguo, antes de rechazar. Un verificador que solo conoce un secreto convierte cada rotación en una caída.

No hagas trabajo lento en línea. Los proveedores de pagos esperan un 2xx rápido y reintentan si bloqueas en una transacción larga de base de datos. Verifica, encola, confirma, y luego reconcilia fuera de banda, con clave en el id del evento para que los reintentos sigan siendo idempotentes.

Un único error para cada fallo. Devuelve el mismo 401 tanto si la marca de tiempo está obsoleta, como si el id está malformado o el HMAC es incorrecto. Un error detallado (“marca de tiempo incorrecta” frente a “firma incorrecta”) le da a un atacante un oráculo de sondeo.

La tolerancia es un compromiso. Cinco minutos perdonan el desfase habitual de reloj entre tu servidor y el proveedor. Demasiado amplia y un webhook capturado sigue siendo repetible más tiempo del que tu caché lo recuerda; demasiado estrecha y las entregas legítimas fallan cuando un reloj se desvía. Sincroniza el reloj de tu servidor con NTP y mantén la ventana ajustada.

Conclusión

Un webhook entrante es un POST no fiable hasta que pasan cuatro comprobaciones independientes: el HMAC demuestra que vino de tu proveedor, los bytes crudos demuestran que no fue alterado, la marca de tiempo demuestra que es fresco y la caché de repetición demuestra que es nuevo. Omite cualquiera y la parte más silenciosa de tu sistema de licencias —la que revoca ante un reembolso— se convierte en la más fácil de falsificar. Verifica sobre los bytes que realmente se firmaron, compara en tiempo constante y solo entonces deja que un evento de facturación toque una licencia.

Prueba Nebula.NET

Endurece tu código .NET en minutos — empieza con la edición gratuita.