Recibir webhooks de forma fiable

Trainingym entrega los eventos al menos una vez y sin garantía de orden. Tres hábitos hacen tu integración robusta: responde rápido, deduplica y tolera campos desconocidos.

Responde con 2xx, rápido

Una entrega se considera correcta cuando tu endpoint devuelve cualquier 2xx en 10 segundos. Encola el trabajo pesado y confirma de inmediato — un timeout cuenta como fallo y dispara reintentos.

app.MapPost("/webhooks", async (WebhookEnvelope evt, IQueue queue) =>
{
    if (await queue.isDuplicate(evt.idEvent))
        return Results.Ok();          // ya procesado → aun así 2xx

    await queue.enqueue(evt);         // procesa en segundo plano
    return Results.Ok();
});

Deduplica con idEvent

Los reintentos hacen que el mismo evento pueda llegar más de una vez. Trata idEvent como clave de idempotencia: si ya lo has visto, omite el procesamiento y devuelve 2xx igualmente.

Conoce la política de reintentos

Cualquier respuesta que no sea 2xx, o un timeout, reprograma la entrega con este backoff, hasta 14 reintentos:

Intento	Espera
1–2	1m · 2m
3–4	10m · 30m
5–9	1h → 2h → 4h → 8h → 12h
10–14	cada 1 día

Sé compatible hacia delante

Con el tiempo pueden añadirse campos nuevos a las cargas útiles. Parsea de forma tolerante e ignora lo que no reconozcas — no falles una entrega por un campo inesperado.

Checklist

• El endpoint devuelve 2xx en menos de 10 segundos
• El trabajo largo se encola, no se hace en línea
• idEvent se almacena y se comprueba antes de procesar
• Los campos desconocidos se ignoran, no se rechazan