Balla StatsAll Tutorials

Webhooks

Set up real-time event notifications to push data to your external systems whenever events occur in your group.

Advanced
15 minutes

Prerequisites

Before setting up webhooks, you need:

  • A Balla Stats account
  • TEAM plan or higher
  • Admin or Owner role in the group
  • Basic understanding of HTTP endpoints

Plan limits: TEAM = 5 webhooks (10,000 events/day), ENTERPRISE = 50 webhooks (unlimited events/day). FREE and PRO plans do not include webhooks.

Real-Time Event Notifications

Receive instant notifications when events occur in your group. Webhooks push data to your external systems in real-time.

21 Event Types

Match, goal, card, season, registration, player, team events

HMAC Signatures

Verify payload authenticity

Automatic Retries

Reliable delivery with exponential backoff

What You'll Learn
  • Navigate to webhooks
  • Create a webhook
  • Understand event types
  • Verify webhook signatures
  • Test your webhook
  • Monitor delivery logs
  • Retry behavior & auto-disable
  • Regenerate secret
1
Navigate to Webhooks

Open your group's Settings page and click the Webhooks tab. This is where you manage all webhook configurations for your group.

Webhooks tab in group settings
2
Create a Webhook

Click "Create Webhook", enter a descriptive name, your target URL, and select the events you want to subscribe to from the 21 available event types.

Create webhook dialog with event type selection
3
Understand Event Types

Webhooks support 21 event types across 7 categories. Subscribe only to the events your integration needs.

Match Events (5)

match.created, match.started, match.ended, match.completed, match.cancelled

Goal Events (2)

goal.scored, goal.deleted

Card Events (2)

card.yellow, card.red

Substitution Events (1)

substitution.made

Season Events (3)

season.created, season.started, season.ended

Registration Events (3)

registration.created, registration.updated, registration.cancelled

Player Events (3)

player.created, player.updated, player.deleted

Team Events (3)

team.created, team.updated, team.deleted

4
Verify Webhook Signatures

Every webhook delivery includes an HMAC-SHA256 signature so you can verify the payload came from Balla Stats. The following headers are included with each delivery:

  • X-Webhook-Signature — HMAC-SHA256 signature of the payload
  • X-Webhook-Id — Webhook configuration ID
  • X-Webhook-Event-Id — Unique event ID for idempotency
  • X-Webhook-Timestamp — ISO 8601 timestamp of the event

Here is a Node.js example for verifying the 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)
  );
}

Always verify webhook signatures in production to prevent payload spoofing.

5
Test Your Webhook

Click the "Test" button to send a test event to your endpoint. View the delivery result to confirm your endpoint is receiving and processing correctly.

Webhook test delivery result showing success
6
Monitor Delivery Logs

View the complete delivery history for each webhook. Each log entry shows the delivery status (DELIVERED, FAILED, RETRYING), HTTP status code, response time, and any error messages.

Webhook delivery log history with status and timing
7
Retry Behavior & Auto-Disable

Failed deliveries are automatically retried with exponential backoff. The default configuration is 3 retries with increasing delays:

  • Attempt 1: 60 seconds after initial failure
  • Attempt 2: 120 seconds after first retry
  • Attempt 3: 240 seconds after second retry

After 10 consecutive failures, the webhook is automatically disabled to prevent wasted resources. You can re-enable it manually after fixing the issue with your endpoint.

8
Regenerate Secret

If your webhook secret is compromised, regenerate it immediately. Update your receiving endpoint with the new secret before the next delivery to ensure signature verification continues to work.

Regenerating the secret invalidates the old secret immediately. Update your endpoint first to avoid failed signature checks.

Webhook Payload Format

Every webhook delivery sends a JSON payload with the following structure:

{
  "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"
  }
}
Tips

Use a Testing Tool First

Start with webhook.site or requestbin.com for testing before using your production endpoint.

Subscribe Selectively

Subscribe only to the events you need to reduce noise and stay within your daily event limit.

Implement Idempotency

Implement idempotency using the event ID to handle potential duplicate deliveries.

Log Received Payloads

Log received payloads on your end for debugging delivery issues.

Common Issues

Webhook Not Firing

  • Check that the webhook is active and not auto-disabled
  • Verify the webhook is subscribed to the correct event type
  • Ensure your group plan supports webhooks (TEAM or higher)

Signature Verification Failing

  • Use the raw request body for HMAC calculation, not a parsed object
  • Check for character encoding differences between your server and the payload
  • Ensure the secret has not been regenerated since your last configuration

Webhook Auto-Disabled

  • 10 consecutive failures triggered auto-disable to prevent wasted resources
  • Fix the issue with your endpoint, then re-enable the webhook manually
  • Check delivery logs for error details on what caused the failures

Was this article helpful?