Webhook
Configura notifiche di eventi in tempo reale per inviare dati ai tuoi sistemi esterni ogni volta che si verificano eventi nel tuo gruppo.
Prerequisiti
Prima di configurare i webhook, è necessario:
- Un account Balla Stats
- Piano TEAM o superiore
- Ruolo di amministratore o proprietario nel gruppo
- Comprensione di base degli endpoint HTTP
Limiti del piano: TEAM = 5 webhook (10.000 eventi/giorno), ENTERPRISE = 50 webhook (eventi illimitati/giorno). I piani FREE e PRO non includono webhook.
Ricevi notifiche istantanee quando si verificano eventi nel tuo gruppo. I webhook inviano i dati ai tuoi sistemi esterni in tempo reale.
21 Tipi di eventi
Partita, gol, cartellino, stagione, registrazione, giocatore, eventi della squadra
Firme HMAC
Verifica l'autenticità del carico utile
Nuovi tentativi automatici
Consegna affidabile con backoff esponenziale
- Passare ai webhook
- Crea un webhook
- Comprendere i tipi di eventi
- Verifica le firme dei webhook
- Metti alla prova il tuo webhook
- Monitorare i registri di consegna
- Riprova il comportamento e disattiva automaticamente
- Rigenera segreto
Apri la pagina Settings del tuo gruppo e fai clic sulla scheda Webhooks. Qui è dove gestisci tutte le configurazioni dei webhook per il tuo gruppo.
Fai clic su "Crea Webhook", inserisci un nome descrittivo, l'URL di destinazione e seleziona gli eventi a cui desideri iscriverti tra i 21 tipi di eventi disponibili.
I webhook supportano 21 tipi di eventi in 7 categorie. Iscriviti solo agli eventi di cui hai bisogno per la tua integrazione.
Eventi della partita (5)
match.created, match.started, match.ended, match.completed, match.cancelled
Eventi gol (2)
goal.scored, goal.deleted
Eventi delle carte (2)
card.yellow, card.red
Eventi di sostituzione (1)
substitution.made
Eventi stagionali (3)
season.created, season.started, season.ended
Eventi di registrazione (3)
registration.created, registration.updated, registration.cancelled
Eventi giocatore (3)
player.created, player.updated, player.deleted
Eventi di squadra (3)
team.created, team.updated, team.deleted
Ogni consegna di webhook include una firma HMAC-SHA256 in modo da poter verificare che il payload provenga da Balla Stats. Le seguenti intestazioni sono incluse in ogni consegna:
X-Webhook-Signature— Firma HMAC-SHA256 del carico utileX-Webhook-Id— ID di configurazione del webhookX-Webhook-Event-Id— ID evento univoco per idempotenzaX-Webhook-Timestamp— Timestamp ISO 8601 dell'evento
Ecco un esempio Node.js per verificare la firma:
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)
);
}Verifica sempre le firme dei webhook in produzione per evitare lo spoofing del payload.
Fai clic sul pulsante "Test" per inviare un evento di test al tuo endpoint. Visualizza il risultato della consegna per confermare che il tuo endpoint sta ricevendo ed elaborando correttamente.
Visualizza la cronologia completa delle consegne per ciascun webhook. Ogni voce di registro mostra lo stato di consegna (DELIVERED, FAILED, RETRYING), il codice di stato HTTP, il tempo di risposta ed eventuali messaggi di errore.
Le consegne non riuscite vengono ritentate automaticamente con un backoff esponenziale. La configurazione predefinita prevede 3 tentativi con ritardi crescenti:
- Tentativo 1: 60 secondi dopo il fallimento iniziale
- Tentativo 2: 120 secondi dopo il primo tentativo
- Tentativo 3: 240 secondi dopo il secondo tentativo
Dopo 10 errori consecutivi, il webhook viene automaticamente disabilitato per evitare sprechi di risorse. Puoi riattivarlo manualmente dopo aver risolto il problema con il tuo endpoint.
Se il segreto del tuo webhook è compromesso, rigeneralo immediatamente. Aggiorna il tuo endpoint di ricezione con il nuovo segreto prima della consegna successiva per garantire che la verifica della firma continui a funzionare.
La rigenerazione del segreto invalida immediatamente il vecchio segreto. Aggiorna prima il tuo endpoint per evitare controlli di firma non riusciti.
Ogni consegna del webhook invia un payload JSON con la seguente struttura:
{
"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"
}
}Utilizza prima uno strumento di test
Inizia con webhook.site o requestbin.com per eseguire i test prima di utilizzare l'endpoint di produzione.
Iscriviti selettivamente
Iscriviti solo agli eventi di cui hai bisogno per ridurre il rumore e rimanere entro il limite di eventi giornalieri.
Implementare l'idempotenza
Implementa l'idempotenza utilizzando l'ID evento per gestire potenziali consegne duplicate.
Registra i payload ricevuti
Registra i payload ricevuti per il debug dei problemi di consegna.
Il webhook non si attiva
- Verifica che il webhook sia attivo e non disabilitato automaticamente
- Verificare che il webhook sia sottoscritto al tipo di evento corretto
- Assicurati che il tuo piano di gruppo supporti i webhook (TEAM o superiore)
Verifica della firma non riuscita
- Utilizzare il corpo della richiesta non elaborata per il calcolo HMAC, non un oggetto analizzato
- Controlla le differenze nella codifica dei caratteri tra il tuo server e il payload
- Assicurati che il segreto non sia stato rigenerato dall'ultima configurazione
Webhook disabilitato automaticamente
- 10 guasti consecutivi hanno attivato la disattivazione automatica per evitare sprechi di risorse
- Risolvi il problema con l'endpoint, quindi riattiva manualmente il webhook
- Controllare i log di consegna per i dettagli degli errori e le cause degli errori