Webhooks de eventos de licencia salientes de Keyright
Deja de sondear la API de licencias para enterarte de lo que cambió. Así es como Keyright envía eventos de ciclo de vida firmados — activada, revocada, renovada, por vencer — a tu propio endpoint, y cómo verificar la firma, sobrevivir a la entrega al-menos-una-vez y rechazar repeticiones en el lado receptor.
La mayoría de los equipos se entera de lo que hizo su sistema de licencias preguntándoselo. Un trabajo nocturno trae la lista de licencias activas, la compara con la de ayer y dispara los correos y las actualizaciones de CRM que deberían haber salido horas antes. Funciona hasta que importa: un cliente pide un reembolso a las 9am, tu panel de “clientes activos” lo sigue contando a las 5pm y un recordatorio de renovación aterriza en la bandeja de alguien que se fue la semana pasada. El sondeo siempre está desactualizado por diseño, y cuanto más fino cortas el intervalo, más machacas una API para enterarte, en su mayoría, de que nada cambió.
La solución es invertir el flujo. En lugar de que tus sistemas pregunten al servicio emisor qué cambió, el servicio emisor te avisa en el momento en que cambia. Eso hacen los webhooks de eventos salientes de Keyright: un POST HTTP firmado a un endpoint tuyo, cada vez que una licencia cruza un límite de su ciclo de vida. Este artículo trata de consumirlos correctamente — la firma, las garantías de entrega y la ventana de repetición — porque un endpoint de webhook es una puerta pública a tu back-office, y los tres detalles que lo hacen seguro son fáciles de equivocar.
Cómo es un evento
Cada evento es un pequeño documento JSON con un sobre estable. El type te dice qué pasó; el data lleva la licencia a la que le pasó. Los campos del sobre — id, type, created — son los mismos en todos los eventos, así que un único handler puede enrutar por type y confiar en el resto de la forma.
{
"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"
}
}
Los eventos de ciclo de vida que realmente conectarás son una lista corta:
license.activated— una clave vinculada a un nuevo dispositivo o asiento. Dispara aprovisionamiento, correo de bienvenida, sincronización del recuento de asientos.license.validated.new_node— una licencia existente hizo check-in desde un dispositivo que nunca había usado. Útil para monitorizar abusos.license.renewed— una renovación pagada extendió el vencimiento. Actualiza la fecha de “pagado hasta” en tu CRM.license.expiring— el planificador del servicio emisor se activó porque una licencia está dentro de su ventana de renovación (digamos, a 14 días). Impulsa la secuencia de cobro.license.revoked— una clave fue revocada (reembolso, contracargo, acción manual). Cambia feature flags, notifica a soporte.
El camino de entrega
Un evento se produce en el instante en que el servicio emisor confirma el cambio de estado, se entrega a un worker de entrega y se hace POST a tu URL suscrita. Si tu endpoint es lento, está caído o devuelve un no-2xx, el worker reintenta con backoff. Ese comportamiento de reintento es lo más importante que hay que diseñar, y el diagrama hace concreta la consecuencia: el mismo evento puede llegar más de una vez.
Esto es entrega al-menos-una-vez, y es la garantía correcta: la alternativa — a-lo-sumo-una-vez — descartaría silenciosamente eventos cada vez que tu endpoint tropezara, lo cual es peor que verlo dos veces. Tu trabajo en el lado receptor es hacer que un duplicado sea inofensivo.
Detalle 1 — verifica la firma sobre el cuerpo crudo
Cualquiera que descubra tu URL de webhook puede alcanzarla. Si tu handler actúa sobre lo que recibe, alguien puede hacer POST de un license.renewed para una cuenta que nunca pagó. La defensa es un HMAC que el servicio emisor calcula sobre el payload con un secreto que solo ambos poseen, enviado en X-Keyright-Signature junto a un X-Keyright-Timestamp. La cadena firmada es la marca de tiempo y el cuerpo crudo unidos por un punto — lo que ata la firma a un momento en el tiempo además de a los bytes.
La trampa que atrapa a todos: verifica sobre los bytes crudos exactos que recibiste, antes de deserializar nada. El model binding re-serializa el JSON con otro espaciado y orden de claves, y el HMAC recalculado nunca coincidirá. Lee el cuerpo como string una vez, verifica, y luego analiza.
app.MapPost("/webhooks/keyright", async (HttpRequest req) =>
{
using var reader = new StreamReader(req.Body);
string rawBody = await reader.ReadToEndAsync(); // los bytes exactos, intactos
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)!; // seguro analizar ahora
await _dispatcher.HandleAsync(evt);
return Results.Ok();
});
El verificador recalcula el HMAC y compara en tiempo constante — un simple == sobre las cadenas hex filtra, por el tiempo que tarda, cuántos bytes iniciales coincidieron, lo que basta para falsificar una firma byte a byte. CryptographicOperations.FixedTimeEquals cierra esa puerta.
public static class WebhookVerifier
{
public static bool IsValid(string body, string timestamp, string header, byte[] secret)
{
// Rechaza todo lo más viejo que cinco minutos: achica la ventana de repetición.
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);
}
}
Detalle 2 — haz el consumidor idempotente
Como la entrega es al-menos-una-vez, tu handler debe producir el mismo resultado tanto si ve un evento una vez como cinco. Usa como clave de tu procesamiento el id del sobre, que es estable entre reintentos del mismo evento, y regístralo la primera vez que actúes. Una segunda llegada encuentra el registro y retorna temprano.
public async Task HandleAsync(WebhookEvent evt)
{
// INSERT ... ON CONFLICT DO NOTHING sobre el event id; 0 filas = ya lo vimos.
if (!await _events.TryClaimAsync(evt.Id))
return; // duplicado — ya procesado, confírmalo
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;
// ignora los tipos de evento que no manejas — no devuelvas 4xx, solo confirma
}
}
Fíjate en el último comentario. Devuelve 2xx para los eventos que no te importan. Un 4xx le dice al servicio emisor que la entrega falló, así que seguirá reintentando un evento que nunca ibas a usar, y tu cola de reintentos se atasca detrás de él.
Responde rápido, trabaja después
El worker de entrega tiene un timeout. Si tu handler hace trabajo real — enviar correo, llamar a un CRM — dentro de la petición, una dependencia lenta se convierte en un timeout de webhook y un reintento innecesario. Para cualquier cosa más allá de una escritura rápida, reclama el event id, encola el trabajo a tu propio procesador en segundo plano y devuelve 200 de inmediato. Has confirmado la recepción; el procesamiento es ahora tu problema, no el del servicio emisor.
Configurar una suscripción
Las suscripciones se gestionan con la CLI de Keyright contra tu instancia autohospedada. Crea una con la URL de destino y los tipos de evento que quieres; el comando devuelve el secreto de firma una sola vez, que guardas donde tu app lea sus secretos.
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, secreto de firma whsec_... (se muestra una vez)
Suscríbete solo a los eventos que manejas. Una suscripción más estrecha es menos tráfico, una superficie de ataque más pequeña y un contrato más claro para el siguiente ingeniero que lea tu handler.
Los webhooks notifican; el SDK aplica
Vale la pena enunciar un límite con claridad, porque confundirlo causa caídas reales. Los webhooks son para tus sistemas de back-office — CRM, correo, paneles, aprovisionamiento. No son cómo la aplicación licenciada decide si ejecutarse. Esa decisión permanece dentro de la app, que inicializa el SDK de Keyright con su producto y clave pública y llama a Validate contra la licencia firmada que posee, controlando funciones de forma 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, local, siempre
Mantén ambas preocupaciones separadas y las dos se simplifican. Un webhook retrasado por una tormenta de reintentos aún no puede permitir que una app sin licencia se ejecute, porque la app nunca confió en el webhook en primer lugar. Y una verificación de licencia que falla sin conexión sigue funcionando, porque no depende de que tu CRM se haya enterado de la noticia. El webhook es cómo tu negocio se entera de un cambio de licencia en tiempo real; la licencia firmada y el gate del SDK son cómo tu software lo aplica.
Prueba Nebula.NET
Endurece tu código .NET en minutos — empieza con la edición gratuita.