Polling an API every few seconds to check for new goals wastes credits and adds latency. Webhooks flip the model: instead of asking "did anything happen?" repeatedly, your server gets notified the instant a goal is scored. This guide covers registering, managing, and securing webhooks with Live Football API.
Why Use Webhooks Instead of Polling
- Instant delivery — notifications arrive the moment a goal happens, no polling delay
- Lower cost — registering is free; you're only charged 1 credit per delivered notification, versus repeated polling calls whether or not anything changed
- Simpler architecture — no need to manage polling intervals or track "last seen" state per match
Registering a Webhook
Registration is a simple POST request with your callback URL:
import requests
response = requests.post(
'https://live-football-api.com/api/v1/webhook/register',
params={'api_key': 'YOUR_KEY'},
json={
'webhook_url': 'https://yourapp.com/webhooks/football',
'label': 'production server'
}
).json()
print(response['data']['message'])
The same request in JavaScript:
const res = await fetch(
'https://live-football-api.com/api/v1/webhook/register?api_key=YOUR_KEY',
{
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
webhook_url: 'https://yourapp.com/webhooks/football',
label: 'production server'
})
}
);
const result = await res.json();
Handling Incoming Webhook Payloads
Your endpoint needs to accept a POST request and return a 2xx response within 10 seconds, or the delivery will be retried up to 3 times. A goal payload looks like this:
{
"event": "goal",
"match_id": "lfa4phmwb3bhclg7aqht1ajcwk",
"timestamp": "2026-07-03T14:46:00Z",
"data": {
"minute": 46,
"team": "home",
"player": "Erling Haaland",
"assist": "Kevin De Bruyne",
"score": { "home": 3, "away": 1 }
}
}
A minimal Express.js handler:
app.post('/webhooks/football', (req, res) => {
const { event, match_id, data } = req.body;
if (event === 'goal') {
console.log(`GOAL! ${data.player} (${data.minute}') — ${data.score.home}-${data.score.away}`);
notifyUsersFollowingMatch(match_id, data);
}
res.sendStatus(200);
});
Securing Your Webhook Endpoint
All webhook notifications are sent from a single, fixed IP address: 45.94.4.69. For added security, restrict incoming requests to your webhook endpoint at the firewall or load balancer level to only accept traffic from this IP.
# Example nginx rule restricting the webhook path to the known sender IP
location /webhooks/football {
allow 45.94.4.69;
deny all;
proxy_pass http://localhost:3000;
}
Managing Existing Webhooks
List all webhooks registered to your account — this call is free:
GET https://live-football-api.com/api/v1/webhook/register?api_key=YOUR_KEY
Remove one when it's no longer needed, also free:
DELETE https://live-football-api.com/api/v1/webhook/register?api_key=YOUR_KEY&id=1
Combining Webhooks with Polling
A common pattern: use webhooks for real-time goal alerts, and still poll /matches once at the start of a session to build the initial match list and scores. This gets you the best of both — an accurate starting state plus zero-latency updates after that.
Frequently Asked Questions
What events do webhooks send besides goals?
Goals are currently the only event type delivered — there's no card, kickoff, or full-time event yet, and no configuration parameter for event types.
Does registering a webhook cost credits?
No, registering, listing, and deleting webhooks are all free. You're only charged 1 credit per delivered goal notification.
What happens if my server is down when a goal is scored?
Delivery is retried up to 3 times if your endpoint doesn't return a 2xx response within 10 seconds. If all retries fail, that notification is not queued indefinitely.
Can I register multiple webhook URLs?
Yes, you can register several webhooks (for example, one for staging and one for production) and manage each independently using its ID.
