Soccer WebSocket API for Real-Time Match Events

What Is a Soccer WebSocket API?

A Soccer WebSocket API keeps a persistent connection open between your application and the data service. Instead of repeatedly requesting the same endpoint to discover whether something changed, the server can deliver supported soccer events as they become available.

This makes WebSocket delivery well suited to live scoreboards, match centres, push notifications, fantasy scoring, trading interfaces, broadcast graphics and any application where users expect updates during the match.

WebSocket should normally be combined with REST. Use REST to load the complete current match state, then use the stream for incremental changes. After a disconnect, reload the authoritative state before continuing.

Soccer Events Available Through WebSocket

Recommended Soccer WebSocket Architecture

1. Authenticate with your backend
2. Request active matches through REST
3. Load the complete selected match state
4. Open the WebSocket connection
5. Subscribe to one or more match channels
6. Process each unique event once
7. Monitor heartbeat messages
8. Detect stale or disconnected sessions
9. Reconnect using controlled backoff
10. Reload the latest REST state
11. Reconcile any missed events
12. Resume live event processing

Authenticate the WebSocket Connection

The production service may authenticate through a connection header, signed token, query parameter or an initial authentication message. Follow the final documentation exactly and avoid exposing permanent private credentials in public browser code.

Illustrative Connection URL

wss://stream.example.com/v1/soccer

Illustrative Authentication Message

{
  "action": "authenticate",
  "token": "SHORT_LIVED_ACCESS_TOKEN"
}

Credential Security

• Keep permanent API credentials on your backend
• Issue short-lived client tokens where supported
• Restrict token scope to required matches or channels
• Expire and rotate compromised credentials
• Use encrypted WSS connections in production
• Validate every subscription on the server

Subscribe to Soccer Match Events

Subscribe only to the matches or competitions your application needs. This reduces unnecessary processing and makes connection state easier to manage.

Subscribe to One Match

{
  "action": "subscribe",
  "channel": "match",
  "match_ids": [
    "match_74021"
  ]
}

Subscribe to Selected Event Types

{
  "action": "subscribe",
  "channel": "match_events",
  "match_ids": [
    "match_74021"
  ],
  "event_types": [
    "goal",
    "yellow_card",
    "red_card",
    "var_decision",
    "penalty",
    "substitution",
    "match_status"
  ]
}

Unsubscribe

{
  "action": "unsubscribe",
  "channel": "match",
  "match_ids": [
    "match_74021"
  ]
}

Example Goal Event

Event payloads should include a unique event identifier, match identifier, type, sequence, timestamp and enough context to update the current interface safely.

{
  "event_id": "event_991827",
  "match_id": "match_74021",
  "type": "goal",
  "sequence": 184,
  "period": "second_half",
  "minute": 67,
  "injury_time": 0,
  "team_id": "team_18",
  "player_id": "player_301",
  "assist_player_id": "player_447",
  "goal_type": "open_play",
  "status": "confirmed",
  "score": {
    "home": 2,
    "away": 1
  },
  "created_at": "2026-08-06T10:31:22Z"
}

Recommended Event Fields

Stream Match Status and Injury Time

Match clocks can pause, move into added time or enter extra time and penalty shootouts. Use the supplied state rather than calculating the official clock only from the connection duration.

Use Heartbeats to Detect Stale Connections

A WebSocket can appear open even when messages are no longer reaching the client. Heartbeat messages help both sides confirm that the connection is active.

Illustrative Server Ping

{
  "type": "ping",
  "timestamp": "2026-08-06T10:31:30Z"
}

Illustrative Client Pong

{
  "type": "pong",
  "timestamp": "2026-08-06T10:31:30Z"
}

Heartbeat Best Practices

• Follow the documented heartbeat interval
• Record the last received heartbeat time
• Mark the interface as stale after a defined timeout
• Close and reconnect unresponsive sessions
• Do not invent an interval until the production value is confirmed

Reconnect Without Missing Soccer Events

Mobile networks, proxy timeouts, deployments and temporary service interruptions can close active connections. A production client should expect this and recover automatically.

Reconnect workflow

1. Detect that the socket closed or became stale
2. Stop treating the current interface as fully live
3. Wait using exponential backoff with jitter
4. Request the latest match state through REST
5. Open a new WebSocket connection
6. Authenticate again
7. Resubscribe to required channels
8. Compare the last processed sequence
9. Apply only missing events
10. Restore the live connection indicator

Illustrative Retry Delays

Attempt 1: short delay
Attempt 2: longer delay
Attempt 3: increased delay
Later attempts: capped maximum delay

Add random jitter to prevent many clients
from reconnecting at exactly the same time.

Connect to a Soccer WebSocket Stream

This browser example is illustrative. Production applications should use the official authentication method and avoid placing permanent private API credentials in public JavaScript.

const socketUrl = 'wss://stream.example.com/v1/soccer';
let socket;
let reconnectAttempt = 0;
let reconnectTimer;

function connect() {
  socket = new WebSocket(socketUrl);

  socket.addEventListener('open', () => {
    reconnectAttempt = 0;

    socket.send(JSON.stringify({
      action: 'authenticate',
      token: 'SHORT_LIVED_ACCESS_TOKEN'
    }));

    socket.send(JSON.stringify({
      action: 'subscribe',
      channel: 'match_events',
      match_ids: ['match_74021']
    }));
  });

  socket.addEventListener('message', (message) => {
    const event = JSON.parse(message.data);

    if (event.type === 'ping') {
      socket.send(JSON.stringify({
        type: 'pong',
        timestamp: event.timestamp
      }));
      return;
    }

    processSoccerEvent(event);
  });

  socket.addEventListener('close', () => {
    scheduleReconnect();
  });

  socket.addEventListener('error', () => {
    socket.close();
  });
}

function scheduleReconnect() {
  clearTimeout(reconnectTimer);

  const baseDelay = Math.min(
    1000 * Math.pow(2, reconnectAttempt),
    30000
  );

  const jitter = Math.floor(Math.random() * 1000);
  reconnectAttempt += 1;

  reconnectTimer = setTimeout(async () => {
    await reloadCurrentMatchState();
    connect();
  }, baseDelay + jitter);
}

connect();

Process Soccer Events on Your Backend

A backend service can maintain one upstream connection and distribute authorised updates to many application users. This can reduce duplicate connections and centralise event validation.

Backend processing pattern

1. Open one authorised upstream WebSocket connection
2. Subscribe to matches currently required by users
3. Validate and store each unique event
4. Update the central match state
5. Publish the event to internal subscribers
6. Cache the latest match state
7. Unsubscribe when the match no longer has active users
8. Load and store the final state at full time

Scale Real-Time Soccer Data Across Many Users

Avoid opening a separate provider connection for every website visitor unless the service is explicitly designed for that model. A common architecture uses one backend ingestion layer and distributes validated updates internally.

Soccer WebSocket API
        |
        v
Live ingestion service
        |
        +-- Event validation
        +-- Duplicate protection
        +-- Match-state cache
        +-- Persistent event store
        |
        v
Internal message broker
        |
        +-- Web application
        +-- Mobile application
        +-- Notification service
        +-- Fantasy scoring
        +-- Analytics pipeline

WebSocket Connection and Subscription Errors

Understanding Real-Time Soccer Update Speed

WebSocket removes the polling interval between requests, but total event delivery time still depends on the original data source, processing, network location, connection quality and your own application.

Do not publish a guaranteed millisecond latency, response time, uptime or update frequency unless it has been confirmed by measured service data or a contractual service-level agreement.

What Can You Build With a Soccer Streaming API?

Soccer WebSocket Integration Checklist

• Use the confirmed WSS endpoint and authentication method
• Load complete match state through REST before subscribing
• Store unique event IDs and sequence values
• Handle goals, cards, substitutions and status events separately
• Respond to required heartbeat messages
• Detect stale connections
• Reconnect with capped exponential backoff and jitter
• Reload REST state after reconnecting
• Prevent duplicate event processing
• Monitor connection, subscription and event-processing errors
• Stop subscriptions after the match is final
• Reconcile the final result and statistics

Soccer WebSocket API Coverage

Streaming coverage may include international competitions, domestic leagues, cups and selected youth or women’s competitions. Available event types can vary by competition, season and subscription plan.

Before launch, confirm whether the required competitions include goals, cards, VAR decisions, substitutions, penalties, line-ups, match status, injury time and live statistics through WebSocket.

Soccer WebSocket API FAQs