Webhooks
Configurez des notifications d'evenements en temps reel pour envoyer des donnees a vos systemes externes chaque fois que des evenements se produisent dans votre groupe.
Prerequis
Avant de configurer les webhooks, vous avez besoin de :
- Un compte Balla Stats
- Plan TEAM ou superieur
- Role d'administrateur ou proprietaire dans le groupe
- Comprehension de base des endpoints HTTP
Limites du plan : TEAM = 5 webhooks (10 000 evenements/jour), ENTERPRISE = 50 webhooks (evenements illimites/jour). Les plans FREE et PRO n'incluent pas les webhooks.
Recevez des notifications instantanees lorsque des evenements se produisent dans votre groupe. Les webhooks envoient des donnees a vos systemes externes en temps reel.
21 Types d'evenements
Evenements de match, but, carton, saison, inscription, joueur, equipe
Signatures HMAC
Verifiez l'authenticite du payload
Nouvelles tentatives automatiques
Livraison fiable avec recul exponentiel
- Naviguer vers les webhooks
- Creer un webhook
- Comprendre les types d'evenements
- Verifier les signatures de webhook
- Tester votre webhook
- Surveiller les journaux de livraison
- Comportement de nouvelle tentative et desactivation automatique
- Regenerer le secret
Ouvrez la page Parametres de votre groupe et cliquez sur l'onglet Webhooks. C'est ici que vous gerez toutes les configurations de webhook de votre groupe.
Cliquez sur "Creer un Webhook", entrez un nom descriptif, votre URL cible et selectionnez les evenements auxquels vous souhaitez vous abonner parmi les 21 types d'evenements disponibles.
Les webhooks supportent 21 types d'evenements dans 7 categories. Abonnez-vous uniquement aux evenements dont votre integration a besoin.
Evenements de match (5)
match.created, match.started, match.ended, match.completed, match.cancelled
Evenements de but (2)
goal.scored, goal.deleted
Evenements de carton (2)
card.yellow, card.red
Evenements de remplacement (1)
substitution.made
Evenements de saison (3)
season.created, season.started, season.ended
Evenements d'inscription (3)
registration.created, registration.updated, registration.cancelled
Evenements de joueur (3)
player.created, player.updated, player.deleted
Evenements d'equipe (3)
team.created, team.updated, team.deleted
Chaque livraison de webhook inclut une signature HMAC-SHA256 pour que vous puissiez verifier que le payload provient de Balla Stats. Les en-tetes suivants sont inclus avec chaque livraison :
X-Webhook-Signature— Signature HMAC-SHA256 du payloadX-Webhook-Id— ID de configuration du webhookX-Webhook-Event-Id— ID unique de l'evenement pour l'idempotenceX-Webhook-Timestamp— Horodatage ISO 8601 de l'evenement
Voici un exemple Node.js pour verifier la signature :
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)
);
}Verifiez toujours les signatures de webhook en production pour empecher la falsification de payload.
Cliquez sur le bouton "Tester" pour envoyer un evenement de test a votre endpoint. Consultez le resultat de la livraison pour confirmer que votre endpoint recoit et traite correctement.
Consultez l'historique complet des livraisons pour chaque webhook. Chaque entree du journal montre l'etat de livraison (DELIVERED, FAILED, RETRYING), le code d'etat HTTP, le temps de reponse et les messages d'erreur.
Les livraisons echouees sont automatiquement retentees avec un recul exponentiel. La configuration par defaut est de 3 tentatives avec des delais croissants :
- Tentative 1 : 60 secondes apres l'echec initial
- Tentative 2 : 120 secondes apres la premiere tentative
- Tentative 3 : 240 secondes apres la deuxieme tentative
Apres 10 echecs consecutifs, le webhook est automatiquement desactive pour eviter le gaspillage de ressources. Vous pouvez le reactiver manuellement apres avoir resolu le probleme avec votre endpoint.
Si votre secret de webhook est compromis, regenerez-le immediatement. Mettez a jour votre endpoint recepteur avec le nouveau secret avant la prochaine livraison pour assurer que la verification de signature continue de fonctionner.
La regeneration du secret invalide immediatement l'ancien secret. Mettez a jour votre endpoint d'abord pour eviter les echecs de verification de signature.
Chaque livraison de webhook envoie un payload JSON avec la structure suivante :
{
"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"
}
}Utilisez d'abord un outil de test
Commencez avec webhook.site ou requestbin.com pour les tests avant d'utiliser votre endpoint de production.
Abonnez-vous selectivement
Abonnez-vous uniquement aux evenements dont vous avez besoin pour reduire le bruit et rester dans votre limite quotidienne d'evenements.
Implementez l'idempotence
Implementez l'idempotence en utilisant l'ID de l'evenement pour gerer les livraisons potentiellement en double.
Enregistrez les payloads recus
Enregistrez les payloads recus de votre cote pour deboguer les problemes de livraison.
Le webhook ne se declenche pas
- Verifiez que le webhook est actif et n'a pas ete desactive automatiquement
- Verifiez que le webhook est abonne au bon type d'evenement
- Assurez-vous que le plan de votre groupe prend en charge les webhooks (TEAM ou superieur)
Echec de la verification de signature
- Utilisez le corps brut de la requete pour le calcul HMAC, pas un objet parse
- Verifiez les differences d'encodage de caracteres entre votre serveur et le payload
- Assurez-vous que le secret n'a pas ete regenere depuis votre derniere configuration
Webhook desactive automatiquement
- 10 echecs consecutifs ont declenche la desactivation automatique pour eviter le gaspillage de ressources
- Corrigez le probleme avec votre endpoint, puis reactivez le webhook manuellement
- Consultez les journaux de livraison pour les details d'erreur sur les causes des echecs
Cet article vous a-t-il ete utile?