Webhook de eventos de jogos de futebol

Um pedido HTTP POST por evento, para os eventos que escolheres:

• Pontapé de saída
• Golos, com o marcador e a assistência quando os nossos dados os indicam
• Cartões amarelos e vermelhos
• Substituições
• Resultado ao intervalo
• Resultado final
• Para uma liga ou uma equipa: os novos vídeos e Shorts do YouTube dos canais que seguimos para elas

Segue uma liga inteira, uma equipa, um jogador ou um único jogo. Uma liga abrange todos os seus jogos. Um jogador recebe só os eventos em que aparece: golos, assistências, cartões e substituições. Se seguires um único jogo, os envios param sozinhos após o apito final.

O corpo é o próprio evento, com os mesmos campos para todos os tipos, por isso um único handler trata de todos.

Um golo, tal como o teu endpoint o recebe (valores de exemplo; a ordem dos campos pode variar):

POST /hooks/9f2c51e7a4 HTTP/1.1
Content-Type: application/json

{
  "eventId": "6f1d2c3e-8a4b-4c5d-9e6f-7a8b9c0d1e2f",
  "matchId": "1234567",
  "type": "goal",
  "country": "England",
  "countryId": "44",
  "countryLogo": "https://example.com/flags/england.png",
  "league": "Coastal League",
  "leagueId": "300",
  "leagueLogo": "https://example.com/logos/coastal-league.png",
  "matchStadium": "Riverside Park",
  "matchReferee": "M. Keller",
  "teamHome": "Riverside FC",
  "teamHomeId": "5001",
  "teamHomeBadge": "https://example.com/badges/riverside-fc.png",
  "teamHomeScore": "1",
  "teamAway": "Northbridge Athletic",
  "teamAwayId": "5002",
  "teamAwayBadge": "https://example.com/badges/northbridge-athletic.png",
  "teamAwayScore": "0",
  "time": "31",
  "score": "1 - 0",
  "side": "home",
  "player1": "J. Moreno",
  "player1Id": "70001",
  "player2": "L. Okafor",
  "player2Id": "70002",
  "card": "",
  "timestamp": { "_seconds": 1792855872, "_nanoseconds": 512000000 }
}

O teu endpoint tem de aceitar um pedido POST com corpo JSON e responder com um estado 2xx. Eis uma versão mínima em Node.js, com um caminho difícil de adivinhar que funciona como segredo:

import http from "node:http";

http.createServer((req, res) => {
  if (req.method !== "POST" || req.url !== "/hooks/9f2c51e7a4") return res.writeHead(404).end();
  let body = "";
  req.on("data", (chunk) => (body += chunk));
  req.on("end", () => {
    const event = JSON.parse(body);
    if (event.type === "goal") console.log(`${event.player1} scores: ${event.teamHome} ${event.score} ${event.teamAway}`);
    res.writeHead(204).end();
  });
}).listen(8080);

Publica-o num endereço HTTPS público.

• Inicia sessão no Football Live Score e abre a página da liga, da equipa, do jogador ou do jogo que queres seguir.
• Seleciona Criar integração, dá-lhe um nome e escolhe Webhook HTTP como destino.
• Cola o endereço do teu endpoint em URL do webhook e seleciona Enviar mensagem de teste. O teu endpoint recebe um pedido cujo corpo é apenas {"type": "✅ Football Live Score: a tua integração está a funcionar."}. Responde com um estado 2xx e o teste passa.
• Escolhe os eventos. Golo já está selecionado.
• Seleciona Criar integração.

Na app, toca no botão de transmissão no ecrã de um jogo, equipa, liga ou jogador, adiciona um destino Servidor HTTP com o mesmo URL, escolhe os eventos e inicia a transmissão.

Todos os pedidos têm os mesmos campos. Todos os valores são strings, exceto timestamp e, nos eventos do YouTube, post. Um campo que não se aplica ao evento é uma string vazia.

• eventId: ID único do evento. Se duas das tuas integrações abrangerem o mesmo evento, os dois pedidos trazem o mesmo eventId, para poderes descartar os duplicados.
• type: match_started, match_half_time, match_ended, goal, card, substitution, youtube ou youtube-short.
• matchId: o ID do jogo (vazio nos eventos do YouTube).
• country, countryId, countryLogo: o país da competição, o respetivo ID e o URL da bandeira.
• league, leagueId, leagueLogo: o nome, o ID e o URL do logótipo da competição.
• matchStadium, matchReferee: estádio e árbitro, quando conhecidos.
• teamHome, teamHomeId, teamHomeBadge, teamHomeScore: nome, ID, URL do emblema e resultado atual da equipa da casa.
• teamAway, teamAwayId, teamAwayBadge, teamAwayScore: o mesmo para a equipa visitante.
• time: o minuto de um golo, cartão ou substituição, tal como o nosso feed de dados o escreve.
• score: o resultado no formato "casa - fora", por exemplo "1 - 0". Num golo, o resultado depois desse golo.
• side: home ou away, ou seja, a equipa que marcou, viu o cartão ou fez a substituição.
• player1, player1Id: o marcador do golo, o jogador que viu o cartão ou o jogador que entra.
• player2, player2Id: o jogador que fez a assistência (vazio se não houver) ou o jogador que sai.
• card: o cartão tal como o nosso feed de dados lhe chama, por exemplo "yellow card" ou "red card".
• timestamp: quando registámos o evento, como um objeto com _seconds (tempo Unix) e _nanoseconds.
• post: só nos eventos do YouTube, o vídeo, incluindo post.youtubeData.title, post.youtubeData.url e post.channelDisplayName.

• Formato: um pedido POST com Content-Type: application/json e o evento como corpo. Um pedido por evento e por integração, nunca agrupados.
• Sucesso: qualquer estado 2xx. Um estado 4xx ou 5xx, ou um erro de ligação, conta como falha.
• Sem novas tentativas: uma entrega falhada não volta a ser enviada. Aparece como erro no registo da integração.
• Falhas repetidas: após várias falhas seguidas, a integração passa para Erro e deixa de enviar. Uma entrega bem-sucedida repõe a contagem a zero.
• Ordem: os pedidos são enviados de forma independente, por isso dois eventos do mesmo minuto podem chegar por qualquer ordem.
• Segurança: os pedidos não são assinados nem levam token. Usa um endereço HTTPS com uma parte aleatória longa, como no exemplo, e ignora pedidos para qualquer outro caminho.
• Pedido de teste: o botão de teste envia só o campo type, por isso garante que o teu handler aceita um corpo sem os outros campos.

Não. Dás-nos um URL. Não há chave para pedir, renovar ou enviar.

Sim. Seleciona apenas Golo ao criar a integração. Podes mudar os eventos mais tarde com Editar.

Provavelmente porque duas das tuas integrações o abrangem, por exemplo uma para a liga e outra para a equipa. Cada uma envia o evento, com o mesmo eventId. Descartar eventIds repetidos resolve isto, e também as raras entregas repetidas.

Sim. A app chama-lhe "Servidor HTTP" e o site "Webhook HTTP". Ambos enviam o mesmo pedido.

Assim que o evento entra nos nossos dados em direto: a mensagem chega em poucos minutos.

No site, abre a tua conta e depois Integrações. Cada integração mostra o estado, quantas mensagens foram enviadas ou falharam, um registo das últimas entregas e botões para a pausar, editar ou eliminar. Na app, as tuas transmissões estão no separador Conta.

Uma integração que segue um único jogo termina sozinha no fim do jogo. As que seguem uma liga, uma equipa ou um jogador continuam, jogo após jogo, até as pausares ou eliminares.

Todas as ligas e taças da nossa página de cobertura.

De momento, as integrações são gratuitas. Mais tarde poderá haver uma subscrição.

Telegram · Discord · Slack

Guias: Como iniciar uma transmissão · Variáveis das mensagens