Webhooks
Stel realtime gebeurtenismeldingen in om gegevens naar uw externe systemen te sturen wanneer er gebeurtenissen plaatsvinden in uw groep.
Vereisten
Voordat u webhooks instelt, heeft u het volgende nodig:
- Een Balla Stats-account
- TEAM-abonnement of hoger
- De rol Beheerder of Eigenaar in de groep
- Basiskennis van HTTP-eindpunten
Planlimieten: TEAM = 5 webhooks (10.000 evenementen/dag), ENTERPRISE = 50 webhooks (onbeperkt evenementen/dag). FREE- en PRO-abonnementen bevatten geen webhooks.
Ontvang direct meldingen wanneer er gebeurtenissen plaatsvinden in uw groep. Webhooks pushen gegevens in realtime naar uw externe systemen.
21 gebeurtenistypen
Wedstrijd, doel, kaart, seizoen, registratie, speler, teamevenementen
HMAC-handtekeningen
Authenticiteit van de payload verifiëren
Automatische nieuwe pogingen
Betrouwbare levering met exponentieel uitstel
- Navigeer naar webhooks
- Maak een webhook
- Gebeurtenistypen begrijpen
- Webhookhandtekeningen verifiëren
- Test uw webhook
- Leveringslogboeken controleren
- Gedrag van opnieuw proberen en automatisch uitschakelen
- Geheim
Open de pagina Settings van uw groep en klik op het tabblad Webhooks. Hier beheert u alle webhookconfiguraties voor uw groep.
Klik op "Webhook maken" , voer een beschrijvende naam en uw doel-URL in en selecteer de evenementen waarop u zich wilt abonneren uit de 21 beschikbare gebeurtenistypen.
Webhooks ondersteunen 21 gebeurtenistypen in 7 categorieën. Abonneer u alleen op de evenementen die uw integratie nodig heeft.
Wedstrijdevenementen (5)
match.created, match.started, match.ended, match.completed, match.cancelled
Doelgebeurtenissen (2)
goal.scored, goal.deleted
Kaartgebeurtenissen (2)
card.yellow, card.red
Vervangingsgebeurtenissen (1)
substitution.made
Seizoensevenementen (3)
season.created, season.started, season.ended
Registratie Evenementen (3)
registration.created, registration.updated, registration.cancelled
Spelerevenementen (3)
player.created, player.updated, player.deleted
Teamevenementen (3)
team.created, team.updated, team.deleted
Elke webhook-levering bevat een HMAC-SHA256-handtekening, zodat u kunt verifiëren dat de payload afkomstig is van Balla Stats. Bij elke levering worden de volgende headers meegeleverd:
X-Webhook-Signature— HMAC-SHA256 handtekening van de ladingX-Webhook-Id— Webhook-configuratie-IDX-Webhook-Event-Id— Unieke gebeurtenis-ID voor idempotentieX-Webhook-Timestamp— ISO 8601-tijdstempel van de gebeurtenis
Hier is een Node.js-voorbeeld voor het verifiëren van de handtekening:
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)
);
}Verifieer altijd webhookhandtekeningen in productie om spoofing van de payload te voorkomen.
Klik op de knop "Test" om een testgebeurtenis naar uw eindpunt te verzenden. Bekijk het leveringsresultaat om te bevestigen dat uw eindpunt correct wordt ontvangen en verwerkt.
Bekijk de volledige leveringsgeschiedenis voor elke webhook. Elke logvermelding toont de leveringsstatus (DELIVERED, FAILED, RETRYING), HTTP-statuscode, responstijd en eventuele foutmeldingen.
Mislukte leveringen worden automatisch opnieuw geprobeerd met exponentieel uitstel. De standaardconfiguratie is 3 nieuwe pogingen met toenemende vertragingen:
- Poging 1: 60 seconden na initiële fout
- Poging 2: 120 seconden na eerste nieuwe poging
- Poging 3: 240 seconden na de tweede nieuwe poging
Na 10 opeenvolgende fouten wordt de webhook automatisch uitgeschakeld om verspilling van bronnen te voorkomen. U kunt het handmatig opnieuw inschakelen nadat u het probleem met uw eindpunt hebt opgelost.
Als uw webhookgeheim is aangetast, moet u het onmiddellijk opnieuw genereren. Werk uw ontvangende eindpunt bij met het nieuwe geheim vóór de volgende levering om ervoor te zorgen dat de handtekeningverificatie blijft werken.
Als u het geheim opnieuw genereert, wordt het oude geheim onmiddellijk ongeldig. Update eerst uw eindpunt om mislukte handtekeningcontroles te voorkomen.
Elke webhook-levering verzendt een JSON-payload met de volgende structuur:
{
"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"
}
}Gebruik eerst een testtool
Begin met webhook.site of requestbin.com om te testen voordat u uw productie-eindpunt gebruikt.
Abonneer u selectief
Abonneer u alleen op de evenementen die u nodig heeft om de ruis te verminderen en binnen uw dagelijkse evenementenlimiet te blijven.
Idempotentie implementeren
Implementeer idempotentie met behulp van de gebeurtenis-ID om mogelijke dubbele leveringen af te handelen.
Ontvangen payloads registreren
Registreer ontvangen payloads aan uw kant voor het opsporen van leveringsproblemen.
Webhook wordt niet geactiveerd
- Controleer of de webhook actief is en niet automatisch is uitgeschakeld
- Controleer of de webhook is geabonneerd op het juiste gebeurtenistype
- Zorg ervoor dat uw groepsplan webhooks ondersteunt (TEAM of hoger)
Handtekeningverificatie mislukt
- Gebruik de onbewerkte aanvraagtekst voor HMAC-berekening, niet een geparseerd object
- Controleer op verschillen in tekencodering tussen uw server en de payload
- Zorg ervoor dat het geheim niet opnieuw is gegenereerd sinds uw laatste configuratie
Webhook automatisch uitgeschakeld
- 10 opeenvolgende fouten hebben automatische uitschakeling geactiveerd om verspilling van bronnen te voorkomen
- Los het probleem met uw eindpunt op en schakel de webhook vervolgens handmatig opnieuw in
- Controleer de leveringslogboeken voor foutdetails over de oorzaak van de fouten