Skip to content
← Todas las publicaciones
· Delta1 Labs WebhooksKeyright

Reenviar webhooks fallidos desde una cola de mensajes muertos

Cuando tu endpoint de webhooks cae durante un despliegue, Keyright no descarta los eventos: los reintenta con un calendario de backoff, aparca en una cola de mensajes muertos los que agotan sus intentos y te da un endpoint de administración para inspeccionarlos y reenviarlos. Aquí tienes la máquina de estados de entrega, el registro de intentos y cómo volver a enviar un evento aparcado sin procesar dos veces los que ya llegaron.

Tu reconciliador de facturación escucha license.revoked en un endpoint de webhooks. Un martes publicas un despliegue, el endpoint devuelve 502 durante noventa segundos mientras rotan los nuevos pods y, en esa ventana, tres reembolsos disparan license.revoked. Si el servicio de licencias usara entrega sin garantías, esos tres eventos se han perdido — y tu recuento de “clientes activos” ahora está mal de una forma que ningún reintento corregirá jamás, porque nada recuerda que los eventos existieron. La caída fueron noventa segundos; la deriva de datos es permanente.

La solución no es hacer tu endpoint perfecto. Es hacer que la entrega sea duradera: cada evento se persiste antes de enviarse, se reintenta según un calendario cuando falla y — solo cuando los reintentos están realmente agotados — se aparca en un lugar donde puedas encontrarlo y volver a enviarlo. Este artículo trata del lado productor de los webhooks salientes de Keyright: la máquina de estados de entrega, el calendario de reintentos, la cola de mensajes muertos que atrapa lo que el calendario no puede y el endpoint de reenvío que te deja volver a enviar un evento aparcado sin contar dos veces los que ya llegaron.

Una entrega es un registro, no una llamada sin garantías

La unidad que Keyright rastrea no es el evento — es la entrega: un intento de enviar un evento a una suscripción. Cuando el servicio emisor confirma un cambio de estado, escribe el evento y, por cada suscripción que coincide con ese tipo de evento, una fila de entrega en estado pending. El POST HTTP ocurre después de la confirmación, impulsado por un worker que lee esas filas. Esta es la disciplina habitual del patrón outbox transaccional, y es lo que hace honesta la garantía: el evento está a salvo en disco antes de que nadie prometa entregarlo, así que una caída entre “confirmar” y “enviar” no pierde nada.

Cada entrega acumula un historial a medida que el worker la procesa:

{
  "id": "whd_01JD9Q4ZB2K7M3X8V0",
  "eventId": "evt_01JD9Q4ZB2K7M3X8V0",
  "subscriptionId": "whs_7c1f9a",
  "type": "license.revoked",
  "status": "dead_lettered",
  "attempts": 7,
  "nextAttemptAt": null,
  "attemptHistory": [
    { "at": "2026-11-17T14:02:11Z", "code": 502, "latencyMs": 1200, "error": "Bad Gateway" },
    { "at": "2026-11-17T14:02:26Z", "code": 502, "latencyMs": 1180, "error": "Bad Gateway" },
    { "at": "2026-11-17T14:03:11Z", "code": null, "latencyMs": 30000, "error": "timeout" }
  ]
}

El attemptHistory es la parte que se gana su sitio. Cuando una entrega falla definitivamente, no obtienes un “no funcionó” — obtienes el código de estado y el error de cada intento, lo que te dice al instante si el problema fue tu endpoint (una racha de 502), un fallo de firma en tu lado (una racha de 401 que devolviste) o un handler lento (timeout). La clasificación arranca desde la evidencia, no desde una conjetura.

El calendario de reintentos

Una respuesta distinta de 2xx o un fallo de conexión no da la entrega por perdida — programa el siguiente intento. Keyright usa backoff exponencial con jitter, de modo que una flota de entregas al mismo endpoint en recuperación no reintenta al unísono y lo vuelve a tumbar. El calendario se estira de segundos a horas a lo largo de un número acotado de intentos:

pending delivering delivered retrying dead_lettered 2xx timeout / non-2xx backoff cumplido · quedan intentos intentos agotados reenvío — reencolar mismo event id Intento 1 inmediato · 2 a ~15s · 3 a ~1m · 4 a ~5m · 5 a ~30m · 6 a ~2h · 7 a ~6h, luego mensajes muertos

Un parpadeo de despliegue de noventa segundos cae por completo dentro de los dos o tres primeros intentos, así que el efecto de cara al cliente es nulo — el evento llega unos segundos tarde y nunca te enteras. El calendario es deliberadamente largo en la cola (horas, no minutos) para que una caída más larga — un certificado defectuoso, un error de DNS, un endpoint tras un proveedor cuyo mantenimiento de fin de semana se alargó — aún tenga buenas probabilidades de triunfar en un intento posterior una vez lo arreglas. El número de intentos, eso sí, está acotado. Cuando se agota, la entrega deja de reintentar y pasa a dead_lettered. Reintentar eternamente convertiría una suscripción rota permanentemente en un backlog ilimitado que mataría de hambre a todas las sanas.

Cuando los intentos se agotan: la cola de mensajes muertos

dead_lettered es un estado terminal pero recuperable. La entrega ya no se reintenta automáticamente — nada la empujará de nuevo por su cuenta — pero no se elimina. Se queda en la cola de mensajes muertos con su historial completo de intentos, esperando a que una persona decida qué hacer. Lista la cola a través de la API de administración:

GET /v1/admin/webhooks/deliveries?status=dead_lettered&subscription=whs_7c1f9a HTTP/1.1
Host: license.acme.example
Authorization: Bearer {admin_token}

o desde la CLI, que es donde de verdad ocurre la mayor parte de la clasificación de guardia:

$ keyright webhooks dlq list --subscription whs_7c1f9a
whd_01JD9Q4ZB2K7M3X8V0  license.revoked   7 attempts  last 502  2026-11-17T14:03Z
whd_01JD9Q7PA1F2C9K4M0  license.renewed   7 attempts  last 502  2026-11-17T14:03Z
whd_01JD9QB3X8V0M3K7J2  license.revoked   7 attempts  last 502  2026-11-17T14:03Z

3 dead-lettered deliveries · oldest 2026-11-17T14:03Z

Tres entregas, todas 502, todas fechadas dentro de tu ventana de despliegue — la cola te ha dicho exactamente cuánto te costó la caída y qué eventos hay que reenviar. La cola de mensajes muertos hace dos trabajos a la vez aquí: es una red de seguridad que conservó los eventos y es un registro de incidente que acota el radio de impacto.

Reenviar una entrega aparcada

El reenvío vuelve a encolar una entrega de la cola de mensajes muertos como una nueva entrega pending del mismo evento — mismo eventId, mismos bytes de payload, mismas entradas de firma. Tu endpoint ve exactamente lo que habría visto en el primer intento:

# Volver a enviar una entrega...
$ keyright webhooks replay whd_01JD9Q4ZB2K7M3X8V0
whd_01JD9Q4ZB2K7M3X8V0 → re-enqueued as whd_01JDA2M5R0 (pending)

# ...o cada entrega en mensajes muertos de una suscripción, una vez el endpoint está sano.
$ keyright webhooks dlq replay --subscription whs_7c1f9a --all
3 deliveries re-enqueued

La misma acción es un endpoint de administración, que es lo que llama tu propia automatización de recuperación:

// Tras un health check que confirma que el endpoint volvió, vacía su cola de mensajes muertos.
async Task DrainDeadLetterQueueAsync(string subscriptionId, CancellationToken ct)
{
    var parked = await _admin.ListDeliveriesAsync(
        status: DeliveryStatus.DeadLettered,
        subscription: subscriptionId,
        ct: ct);

    foreach (var delivery in parked)
    {
        // El reenvío preserva el eventId original, así que un consumidor que deduplica
        // por eventId trata un evento ya procesado como una operación nula e inofensiva.
        await _admin.ReplayDeliveryAsync(delivery.Id, ct);
    }
}

La razón por la que un reenvío en bloque es seguro sin averiguar primero cuál de los tres eventos sí acabó procesando tu endpoint es que el event id no cambia al reenviar. El lado consumidor ya está construido para sobrevivir a la entrega al menos una vez — registra cada eventId que ha procesado e ignora una repetición — así que volver a enviar toda la cola es idempotente desde el punto de vista del receptor. Una entrega que de verdad llegó en el intento 6 (y por tanto nunca fue a mensajes muertos) no está en la cola en absoluto; una que fue a mensajes muertos pero se había procesado parcialmente se reconoce por su id y se descarta. No tienes que ser preciso con la frontera. Reenvías todo lo que quedó aparcado y dejas que la deduplicación del consumidor lo ordene.

// El lado receptor que hace seguro el reenvío a ciegas: deduplica por eventId.
app.MapPost("/webhooks/keyright", async (HttpRequest req, LedgerDb db) =>
{
    var raw = await ReadRawBodyAsync(req);
    if (!WebhookSignature.IsValid(req, raw, _secret))
        return Results.Unauthorized();

    var evt = JsonSerializer.Deserialize<WebhookEvent>(raw)!;

    // El primero en escribir gana; un duplicado reenviado choca en el eventId único y se descarta.
    if (!await db.TryRecordProcessedAsync(evt.Id))
        return Results.Ok();      // ya procesado — confirma y detén los reintentos

    await Reconcile(evt);         // aplica el estado que lleva evt.Data
    return Results.Ok();
});

Cuando el endpoint estará caído más que el calendario

El calendario de reintentos y la cola de mensajes muertos cubren juntos caídas de hasta la ventana de retención. Para una caída planificada más larga que eso — una migración, una reescritura de endpoint de varios días — no dejes que los eventos quemen sus siete intentos contra una URL que sabes muerta y vayan en bloque a mensajes muertos. Pausa la suscripción en su lugar:

$ keyright webhooks pause whs_7c1f9a --reason "endpoint migration"
subscription whs_7c1f9a paused — events held, not delivered

Una suscripción pausada sigue registrando cada evento que coincide pero retiene sus entregas en pending sin intentarlas, de modo que nada envejece fuera de la ventana de retención de mensajes muertos mientras trabajas. Cuando el nuevo endpoint esté activo, keyright webhooks resume whs_7c1f9a libera las entregas retenidas al calendario normal. Pausar intercambia inmediatez por durabilidad de forma deliberada; es la herramienta correcta cuando ya sabes que el endpoint se fue.

Advertencias que conviene decir con claridad

El reenvío no restaura el orden. Las entregas reencoladas corren por el calendario de forma independiente y pueden llegar intercaladas. Si tu handler aplica cambios relativos (“resta un asiento”), un reenvío desordenado corrompe el recuento. Lleva el estado resultante en el payload — el nuevo total de asientos, el expiresAt absoluto — para que cada evento sea una instantánea segura de aplicar en cualquier orden, y reconcilia contra el registro de licencias cuando no lo sea.

Un evento venenoso va a mensajes muertos por tu bug, no por una caída. Si tu handler lanza una excepción con un payload concreto, fallará los siete intentos y quedará aparcado, exactamente igual que un endpoint caído. El historial de intentos lo desambigua — un 500 que devolviste en cada intento apunta a tu código, no a la red — así que léelo antes de reenviar, o simplemente volverás a aparcar el mismo evento.

La retención está acotada. La cola de mensajes muertos es un búfer de recuperación, no un almacén de eventos. Clasifícala dentro de la ventana; para un histórico a largo plazo, consume los eventos license.* en tu propio registro de auditoría según llegan, que es el sistema de referencia que la cola nunca pretendió ser.

Conclusión

La entrega duradera de webhooks son tres mecanismos trabajando juntos. El calendario de reintentos absorbe las caídas breves que son el 99% de la realidad, así que nunca las notas. La cola de mensajes muertos atrapa la cola larga que el calendario no puede vencer y convierte un evento perdido en una fila listada e inspeccionable con su historial completo de fallos. El endpoint de reenvío vuelve a enviar esas filas con sus event ids originales, así que un consumidor que deduplica por event id puede tomar un reenvío en bloque a ciegas y salir consistente. Construye el receptor para que deduplique y aplique instantáneas de estado en lugar de deltas, y recuperarse de una caída del endpoint deja de ser un proyecto de reconciliación de datos y se convierte en un solo comando: lista la cola, reenvíala, listo.

Prueba Nebula.NET

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