Overview
A webhook is an HTTP POST that LIGR sends to your URL when something changes. Use webhooks instead of polling the REST API.
What you get
Section titled “What you get”- One POST per change, for the entities you subscribe to.
- A signed request, so you can prove that LIGR sent it.
- Per-competition subscriptions, so one endpoint can serve many competitions.
- Retries. An event can arrive more than once. An event that fails every attempt is lost.
See Events for the full matrix.
Create a webhook
Section titled “Create a webhook”Webhooks are a dashboard feature. There is no REST endpoint for them. Webhooks are off by default.
- Ask your LIGR contact to turn on webhooks for your organization.
- As an owner or admin, open Organization settings → Developers → Webhooks in the dashboard.
- Select Create webhook. Enter a name and the URL of your endpoint.
- Add the competitions. For each competition, select the entities you want.
- Copy the signing secret from Organization settings → Developers → Webhooks. If the field is empty, select Regenerate signing secret next to it.
Your organization has one signing secret. Every webhook of the organization uses it.
What your endpoint does
Section titled “What your endpoint does”- Read the raw request body. Do not parse it before you verify the signature.
- Verify
x-ligr-webhook-sig. See Verify signatures. - Answer
2xxat once. Process the event after you answer. - Deduplicate on
(entity, data.id, date). Delivery is at least once, so a duplicate is normal.
Your endpoint is your own code, so LIGR cannot check any of these steps. Step 2 is a recommendation. LIGR signs every delivery; verifying that signature is your choice. Steps 3 and 4 change what you receive: a slow answer causes a retry, and a retry arrives whether or not you deduplicate.
LIGR waits 10 seconds for your answer. LIGR retries a delivery with no answer, or with a 5xx,
408 or 429 answer. A match, fact, summary or overlay event gets up to 5 more attempts,
with 30 seconds of retry delays in total. A team or competition event gets up to 2 more
attempts, with 1 minute of retry delays in total. Each attempt can take 10 seconds. See
Delivery health & logs.
Fill a gap from REST
Section titled “Fill a gap from REST”Webhooks carry changes. The REST API holds current state. Read from REST in two cases:
- You start late. A receiver that comes up mid-match, or a webhook enabled after kick-off, has not seen the earlier events. Read the match and its summary once, then apply events as they arrive.
- You lost events. An event that fails every attempt is lost. After an outage on your side longer than 30 seconds, read the entities you track once and continue from the webhooks.
Do not poll REST on a timer as a substitute for webhooks.