Webhooks
Richten Sie Echtzeit-Ereignisbenachrichtigungen ein, um Daten an Ihre externen Systeme zu übertragen, wenn in Ihrer Gruppe Ereignisse auftreten.
Voraussetzungen
Bevor Sie Webhooks einrichten, benötigen Sie Folgendes:
- Ein Balla Stats-Konto
- TEAM-Plan oder höher
- Administrator- oder Besitzerrolle in der Gruppe
- Grundlegendes Verständnis von HTTP-Endpunkten
Plangrenzen: TEAM = 5 Webhooks (10.000 Ereignisse/Tag), ENTERPRISE = 50 Webhooks (unbegrenzte Ereignisse/Tag). FREE- und PRO-Pläne beinhalten keine Webhooks.
Erhalten Sie sofortige Benachrichtigungen, wenn in Ihrer Gruppe Ereignisse auftreten. Webhooks übertragen Daten in Echtzeit an Ihre externen Systeme.
21 Ereignistypen
Spiel, Tor, Karte, Saison, Registrierung, Spieler, Teamevents
HMAC-Signaturen
Authentizität der Nutzlast überprüfen
Automatische Wiederholungsversuche
Zuverlässige Lieferung mit exponentiellem Backoff
- Navigieren Sie zu Webhooks
- Erstellen Sie einen Webhook
- Ereignistypen verstehen
- Webhook-Signaturen überprüfen
- Testen Sie Ihren Webhook
- Überwachen Sie die Zustellungsprotokolle
- Wiederholungsverhalten und automatische Deaktivierung
- Geheimnis neu generieren
Öffnen Sie die Seite Settings Ihrer Gruppe und klicken Sie auf die Registerkarte Webhooks. Hier verwalten Sie alle Webhook-Konfigurationen für Ihre Gruppe.
Klicken Sie auf „Webhook erstellen“ , geben Sie einen beschreibenden Namen und Ihre Ziel-URL ein und wählen Sie aus den 21 verfügbaren Ereignistypen die Ereignisse aus, die Sie abonnieren möchten.
Webhooks unterstützen 21 Ereignistypen in 7 Kategorien. Abonnieren Sie nur die Veranstaltungen, die Ihre Integration erfordert.
Spielereignisse (5)
match.created, match.started, match.ended, match.completed, match.cancelled
Zielereignisse (2)
goal.scored, goal.deleted
Kartenereignisse (2)
card.yellow, card.red
Substitutionsereignisse (1)
substitution.made
Saisonereignisse (3)
season.created, season.started, season.ended
Registrierungsveranstaltungen (3)
registration.created, registration.updated, registration.cancelled
Spielerereignisse (3)
player.created, player.updated, player.deleted
Teamevents (3)
team.created, team.updated, team.deleted
Jede Webhook-Lieferung enthält eine HMAC-SHA256-Signatur, sodass Sie überprüfen können, ob die Nutzlast von Balla Stats stammt. Die folgenden Header sind in jeder Lieferung enthalten:
X-Webhook-Signature— HMAC-SHA256-Signatur der NutzlastX-Webhook-Id— Webhook-Konfigurations-IDX-Webhook-Event-Id— Eindeutige Ereignis-ID für IdempotenzX-Webhook-Timestamp— ISO 8601-Zeitstempel des Ereignisses
Hier ist ein Node.js-Beispiel zur Überprüfung der Signatur:
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)
);
}Überprüfen Sie Webhook-Signaturen immer in der Produktion, um Payload-Spoofing zu verhindern.
Klicken Sie auf die Schaltfläche „Test“, um ein Testereignis an Ihren Endpunkt zu senden. Sehen Sie sich das Übermittlungsergebnis an, um zu bestätigen, dass Ihr Endpunkt korrekt empfängt und verarbeitet.
Sehen Sie sich den vollständigen Zustellungsverlauf für jeden Webhook an. Jeder Protokolleintrag zeigt den Übermittlungsstatus (DELIVERED, FAILED, RETRYING), den HTTP-Statuscode, die Antwortzeit und etwaige Fehlermeldungen.
Fehlgeschlagene Lieferungen werden automatisch mit exponentiellem Backoff wiederholt. Die Standardkonfiguration umfasst 3 Wiederholungsversuche mit zunehmenden Verzögerungen:
- Versuch 1: 60 Sekunden nach dem ersten Fehler
- Versuch 2: 120 Sekunden nach dem ersten Wiederholungsversuch
- Versuch 3: 240 Sekunden nach dem zweiten Wiederholungsversuch
Nach 10 aufeinanderfolgenden Ausfällen wird der Webhook automatisch deaktiviert, um eine Verschwendung von Ressourcen zu verhindern. Sie können es manuell wieder aktivieren, nachdem Sie das Problem mit Ihrem Endpunkt behoben haben.
Wenn Ihr Webhook-Geheimnis gefährdet ist, generieren Sie es sofort neu. Aktualisieren Sie Ihren empfangenden Endpunkt vor der nächsten Zustellung mit dem neuen Geheimnis, um sicherzustellen, dass die Signaturüberprüfung weiterhin funktioniert.
Durch die Neugenerierung des Geheimnisses wird das alte Geheimnis sofort ungültig. Aktualisieren Sie zuerst Ihren Endpunkt, um fehlgeschlagene Signaturprüfungen zu vermeiden.
Jede Webhook-Zustellung sendet eine JSON-Nutzlast mit der folgenden Struktur:
{
"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"
}
}Verwenden Sie zuerst ein Testtool
Beginnen Sie zum Testen mit webhook.site oder requestbin.com, bevor Sie Ihren Produktionsendpunkt verwenden.
Selektiv abonnieren
Abonnieren Sie nur die Veranstaltungen, die Sie benötigen, um den Lärm zu reduzieren und Ihr tägliches Veranstaltungslimit einzuhalten.
Idempotenz implementieren
Implementieren Sie Idempotenz mithilfe der Ereignis-ID, um potenzielle doppelte Lieferungen zu verarbeiten.
Empfangene Nutzlasten protokollieren
Protokollieren Sie empfangene Nutzlasten auf Ihrer Seite, um Zustellungsprobleme zu beheben.
Webhook wird nicht ausgelöst
- Überprüfen Sie, ob der Webhook aktiv und nicht automatisch deaktiviert ist
- Stellen Sie sicher, dass der Webhook den richtigen Ereignistyp
- abonniert hat Stellen Sie sicher, dass Ihr Gruppenplan Webhooks unterstützt (TEAM oder höher)
Signaturüberprüfung schlägt fehl
- Verwenden Sie den rohen Anforderungstext für die HMAC-Berechnung, kein geparstes Objekt
- Suchen Sie nach Unterschieden in der Zeichenkodierung zwischen Ihrem Server und der Nutzlast
- Stellen Sie sicher, dass das Geheimnis seit Ihrer letzten Konfiguration nicht neu generiert wurde
Webhook automatisch deaktiviert
- 10 aufeinanderfolgende Fehler lösten eine automatische Deaktivierung aus, um eine Verschwendung von Ressourcen zu verhindern
- Beheben Sie das Problem mit Ihrem Endpunkt und aktivieren Sie dann den Webhook manuell erneut
- Überprüfen Sie die Zustellungsprotokolle auf Fehlerdetails zu den Fehlerursachen
War dieser Artikel hilfreich?