Skip to main content

Receive webhooks reliably

Trainingym delivers events at-least-once and without ordering guarantees. Three habits make your integration robust: respond fast, deduplicate, and tolerate unknown fields.

Respond with 2xx, quickly​

A delivery is considered successful when your endpoint returns any 2xx within 10 seconds. Enqueue heavy work and acknowledge immediately — a timeout counts as a failure and triggers retries.

app.MapPost("/webhooks", async (WebhookEnvelope evt, IQueue queue) =>
{
    if (await queue.isDuplicate(evt.idEvent))
        return Results.Ok();          // already processed → still 2xx

    await queue.enqueue(evt);         // process in the background
    return Results.Ok();
});

Deduplicate with idEvent​

Retries mean the same event can arrive more than once. Treat idEvent as the idempotency key: if you have seen it, skip processing and still return 2xx.

Know the retry schedule​

Any non-2xx response or timeout re-schedules the delivery on this backoff, up to 14 retries:

AttemptDelay
1–21m · 2m
3–410m · 30m
5–91h → 2h → 4h → 8h → 12h
10–14every 1 day

Be forward-compatible​

New fields may be added to payloads over time. Parse leniently and ignore what you don't recognize — do not fail a delivery because of an unexpected field.

Checklist​

  • Endpoint returns 2xx within 10 seconds
  • Long work is queued, not done inline
  • idEvent is stored and checked before processing
  • Unknown fields are ignored, not rejected