Webhooks
Configure notificações de eventos em tempo real para enviar dados para seus sistemas externos sempre que ocorrerem eventos em seu grupo.
Pré-requisitos
Antes de configurar webhooks, você precisa:
- Uma conta Balla Stats
- Plano TEAM ou superior
- Função de administrador ou proprietário no grupo
- Compreensão básica de endpoints HTTP
Limites do plano: TEAM = 5 webhooks (10.000 eventos/dia), ENTERPRISE = 50 webhooks (eventos ilimitados/dia). Os planos GRATUITO e PRO não incluem webhooks.
Receba notificações instantâneas quando ocorrerem eventos em seu grupo. Webhooks enviam dados para seus sistemas externos em tempo real.
21 Tipos de eventos
Partida, gol, cartão, temporada, inscrição, jogador, eventos da equipe
Assinaturas HMAC
Verifique a autenticidade da carga útil
Novas tentativas automáticas
Entrega confiável com espera exponencial
- Navegue até webhooks
- Crie um webhook
- Entenda os tipos de eventos
- Verifique assinaturas de webhook
- Teste seu webhook
- Monitorar registros de entrega
- Tentar novamente o comportamento e desativar automaticamente
- Regenerar segredo
Abra a página Settings do seu grupo e clique na guia Webhooks. É aqui que você gerencia todas as configurações de webhook do seu grupo.
Clique em "Criar Webhook", insira um nome descritivo, seu URL de destino e selecione os eventos que deseja assinar entre os 21 tipos de eventos disponíveis.
Webhooks suportam 21 tipos de eventos em 7 categorias. Assine apenas os eventos que sua integração precisa.
Eventos de Partida (5)
match.created, match.started, match.ended, match.completed, match.cancelled
Eventos de gol (2)
goal.scored, goal.deleted
Eventos de cartas (2)
card.yellow, card.red
Eventos de substituição (1)
substitution.made
Eventos da Temporada (3)
season.created, season.started, season.ended
Eventos de inscrição (3)
registration.created, registration.updated, registration.cancelled
Eventos de Jogador (3)
player.created, player.updated, player.deleted
Eventos de equipe (3)
team.created, team.updated, team.deleted
Cada entrega de webhook inclui uma assinatura HMAC-SHA256 para que você possa verificar se a carga veio do Balla Stats. Os seguintes cabeçalhos estão incluídos em cada entrega:
X-Webhook-Signature— Assinatura HMAC-SHA256 da cargaX-Webhook-Id— ID de configuração do webhookX-Webhook-Event-Id— ID de evento exclusivo para idempotênciaX-Webhook-Timestamp— Carimbo de hora ISO 8601 do evento
Aqui está um exemplo de Node.js para verificar a assinatura:
const crypto = require('crypto');
function verifySignature(payload, signature, secret) {
const expected = crypto
.createHmac('sha256', secret)
.update(payload)
.digest('hex');
return crypto.timingSafeEqual(
Buffer.from(signature.replace('sha256=', '')),
Buffer.from(expected)
);
}Sempre verifique assinaturas de webhook em produção para evitar falsificação de carga útil.
Clique no botão "Teste" para enviar um evento de teste ao seu endpoint. Visualize o resultado da entrega para confirmar se seu endpoint está recebendo e processando corretamente.
Veja o histórico de entrega completo de cada webhook. Cada entrada de log mostra o status de entrega (DELIVERED, FAILED, RETRYING), código de status HTTP, tempo de resposta e quaisquer mensagens de erro.
Entregas com falha são repetidas automaticamente com espera exponencial. A configuração padrão é de 3 tentativas com atrasos crescentes:
- Tentativa 1: 60 segundos após a falha inicial
- Tentativa 2: 120 segundos após a primeira tentativa
- Tentativa 3: 240 segundos após a segunda tentativa
Após 10 falhas consecutivas, o webhook é automaticamente desabilitado para evitar desperdício de recursos. Você pode reativá-lo manualmente após corrigir o problema com seu endpoint.
Se o segredo do seu webhook estiver comprometido, gere-o novamente imediatamente. Atualize seu endpoint de recebimento com o novo segredo antes da próxima entrega para garantir que a verificação de assinatura continue funcionando.
A regeneração do segredo invalida imediatamente o segredo antigo. Atualize seu endpoint primeiro para evitar falhas nas verificações de assinatura.
Cada entrega de webhook envia uma carga JSON com a seguinte estrutura:
{
"id": "unique-event-id",
"timestamp": "2025-01-16T10:30:00.000Z",
"type": "goal.scored",
"data": {
"matchId": "match-id",
"playerId": "player-id",
"teamId": "team-id",
"minute": 42,
"type": "GOAL"
}
}Use uma ferramenta de teste primeiro
Comece com webhook.site ou requestbin.com para testar antes de usar seu endpoint de produção.
Inscreva-se seletivamente
Assine apenas os eventos necessários para reduzir o ruído e permanecer dentro do limite diário de eventos.
Implementar Idempotência
Implemente a idempotência usando o ID do evento para lidar com possíveis entregas duplicadas.
Registrar cargas úteis recebidas
Registre as cargas recebidas do seu lado para depurar problemas de entrega.
Webhook não dispara
- Verifique se o webhook está ativo e não desabilitado automaticamente
- Verifique se o webhook está inscrito no tipo de evento correto
- Certifique-se de que seu plano de grupo suporta webhooks (TEAM ou superior)
Falha na verificação da assinatura
- Use o corpo bruto da solicitação para cálculo HMAC, não um objeto analisado
- Verifique se há diferenças de codificação de caracteres entre seu servidor e a carga útil
- Certifique-se de que o segredo não tenha sido regenerado desde sua última configuração
Webhook desativado automaticamente
- 10 falhas consecutivas acionaram a desativação automática para evitar desperdício de recursos
- Corrija o problema com seu endpoint e reative o webhook manualmente
- Verifique os logs de entrega para obter detalhes de erros sobre o que causou as falhas