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

• 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.
• At-least-once delivery. An event can arrive more than once. It never arrives at most once.

See Events for the full matrix.

Create a webhook

Webhooks are a dashboard feature. There is no REST endpoint for them.

1. Ask LIGR to enable the f-webhooks feature flag for your organization.
2. Open Developers → Webhooks in the dashboard.
3. Add the URL of your endpoint.
4. Select the competitions and the events you want.
5. Copy the signing secret from Developers → Webhooks.

Your organization has one signing secret. Every webhook of the organization uses it.

Caution

A webhook with no signing secret is skipped without an error. Set the secret before you rely on deliveries.

What your endpoint does

1. Read the raw request body. Do not parse it before you verify the signature.
2. Verify x-ligr-webhook-sig. See Verify signatures.
3. Answer 2xx at once. Process the event after you answer.
4. 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. A delivery with no answer, or with a 5xx, 408 or 429 answer, is retried: match.*, fact.* and summary.* up to 5 more times with 30 seconds of retry delays, other events up to 2 more times with 1 minute of retry delays. Each attempt can take 10 seconds. See Delivery health & logs.

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 a minute, read the entities you track once and continue from the webhooks.

Do not poll REST on a timer as a substitute for webhooks.