Delivery health & logs
Delivery contract
Section titled “Delivery contract”| Behaviour | Today |
|---|---|
| Timeout | 10 seconds. Answer 2xx first, then process |
| Redirects | LIGR follows up to 21 307 or 308 redirects to public HTTP or HTTPS destinations. A 301, 302 or 303 fails the delivery |
| Automatic suspension | Off today. Failed deliveries stay in the log |
| Retries | match.*, fact.*, summary.* and overlay.*: up to 6 attempts with 30 seconds of retry delays. team.* and competition.*: up to 3 attempts with 1 minute of retry delays |
| Ordering | match.*, fact.*, summary.* and overlay.* for one match are sent in order, one at a time. A retried delivery can arrive after a newer event. Across matches there is no guarantee |
| Delivery | At least once. A duplicate is normal, a lost event needs every attempt to fail |
| Idempotency | Use (entity, data.id, date) as the deduplication key |
Redirects must remain on public HTTP/HTTPS destinations. Private-network destinations are rejected.
Use 307 or 308. LIGR does not follow a 301, 302 or 303, because it would drop the POST
body. The delivery fails with that status and is not retried. Cross-host redirects do not retain
Basic Auth credentials.
Retries
Section titled “Retries”LIGR retries a delivery when your endpoint sends no answer, or answers 408, 429 or any 5xx.
LIGR does not retry a 2xx, or any other 4xx. A 4xx means the request itself is wrong for your
endpoint, and a repeat carries the same bytes.
The schedule depends on the event. match.*, fact.*, summary.* and overlay.* events are
delivered in order per match, one at a time, so a failing endpoint must not hold a match for long.
team.* and competition.* events have no order to keep and wait longer.
| Attempt | Match events: wait before it | Other events: wait before it |
|---|---|---|
| 1 | None | None |
| 2 | None | 15 seconds |
| 3 | 2 seconds | 45 seconds |
| 4 | 4 seconds | — |
| 5 | 8 seconds | — |
| 6 | 16 seconds | — |
The waits add up to 30 seconds for a match event and 1 minute for any other event. Each attempt also waits up to 10 seconds for your answer. An event that fails every attempt is lost. Retries cover a restart or a deploy on your side, not an outage. After a longer outage, read the entities you track once from the REST API and continue from the webhooks.
Five rules follow from retries.
- Delivery is at least once. A retry after a lost answer, or a worker that restarts
mid-delivery, sends an event you already processed. Answer
2xxand skip it. - A retry is the same event.
dateis the same on every attempt of one event, so(entity, data.id, date)still deduplicates it. - A retry carries the entity as it is at that moment. The payload is read again for every attempt. Treat every delivery as the latest state of the entity, not as a diff.
- A retry can arrive out of order. A retry goes to the back of the match’s queue, so events
for the same match keep flowing while it waits. Compare
date, orupdatedAton the entity, and ignore an older delivery. - One event counts once towards health. Each attempt is one row in the log. Only the final
failed attempt of an event adds one consecutive failure. One lost event cannot move an endpoint
to
failingon its own.
The dashboard shows the newest 50 attempts per webhook. Open Organization settings → Developers → Webhooks, open the webhook, and select Event Logs. Each row is one attempt. It shows the entity, the type, the attempt number, the status with its text, and the send time. Select View on a row to see the payload and the response body of that attempt.
- The payload is the exact request body that LIGR sent for that attempt. The signature covers the same bytes.
- LIGR keeps a response body only for a failed attempt that got a response.
- The dashboard formats a JSON body for reading. A body larger than 16 KiB stops at 16 KiB and shows a “Truncated” note.
| Status in the log | Meaning |
|---|---|
200–299 | Your endpoint accepted the delivery |
300–599 | The request ended without a successful 2xx response |
0 | Your endpoint sent no response. It timed out, refused the connection or failed DNS |
-500 | LIGR failed before it sent the request |
Health states
Section titled “Health states”LIGR records the result of every delivery and shows one health state per webhook. A broken endpoint
shows as degraded or failing. LIGR does not suspend delivery automatically today.
| State | Meaning | What to do |
|---|---|---|
unknown | No delivery attempted yet | Change something in a subscribed competition |
healthy | The last delivery succeeded | Nothing |
degraded | 1 to 4 consecutive failures, or the last result was a failure | Read your endpoint logs. Deliveries continue |
failing | 5 or more consecutive failures | Investigate the failures. Deliveries continue |
suspended | Delivery was already suspended | Fix the endpoint, then select Re-enable delivery in the webhook menu. LIGR keeps the history |
Keep your endpoint healthy
Section titled “Keep your endpoint healthy”- Answer
2xxin under 10 seconds. Queue the work. - Return
2xxfor an event you already processed. A duplicate is not an error. - Alert on your own 5xx rate. LIGR does not alert you.