Receive real-time event notifications with webhooks

A webhook is an outbound HTTP callback. When an event you subscribe to occurs — such as a match being completed or a participant registering — Tournament Suite sends a JSON payload to a URL on your server. This lets your system react to changes in real time without polling the API.

Where to find it

Developer → Webhooks

Step by step

1. Create a webhook subscription

There's no Add webhook button in the dashboard yet — a webhook subscription (name, endpoint URL, events, and optional signing secret) is created using the same authenticated API access you use for API Keys.

• Endpoint URL — the publicly accessible URL on your server that will receive POST requests from Tournament Suite.
• Events — the event types this subscription should trigger for (see below).
• Signing secret — used to verify that incoming requests genuinely came from Tournament Suite. Strongly recommended.

Once a subscription exists, Developer → Webhooks lists it and gives you read and test access: delivery logs, per-webhook analytics, and a tester — see below.

2. Select the events to subscribe to

Available event types include:

• Tournament — tournament.created, tournament.published, tournament.started, tournament.completed, tournament.cancelled, tournament.updated
• Match — match.created, match.started, match.completed, match.disputed, match.rescheduled, match.forfeited
• Participant — participant.registered, participant.approved, participant.rejected, participant.checked_in, participant.eliminated, participant.disqualified
• Registration — registration.opened, registration.closed, registration.full
• Payment — payment.received, payout.processed, payout.failed
• Broadcast — broadcast.started, broadcast.ended
• Circuit — circuit.created, circuit.season.started, circuit.season.completed
• User — user.created, user.verified, user.suspended
• Anti-cheat — anticheat.detection_raised, anticheat.session_completed

3. Verify the signature

Every webhook request includes an X-Webhook-Signature header and an X-Webhook-Timestamp header. The signature is an HMAC-SHA256 digest of {timestamp}.{request body}, computed with your signing secret and formatted as sha256=<hex digest>.

To verify a request:

1. Recompute the HMAC-SHA256 digest of {timestamp}.{raw request body} using your signing secret.
2. Compare it to the X-Webhook-Signature header using a constant-time comparison.
3. Check that the X-Webhook-Timestamp header is within the last few minutes to reject replayed requests.

The Developer → Webhooks section includes copy-paste signature-verification examples in TypeScript, Python, and PHP.

Testing a webhook

Open Developer → Webhooks → [Webhook] → Test — the Webhook Tester — and click Send test. Your server should respond with HTTP 200 within a few seconds. The response body and status are shown on the same page.

Payload format

Each webhook payload is a JSON object containing:

• event — the event type string (e.g. match.completed)
• timestamp — ISO 8601 timestamp of when the event occurred
• The relevant object for that event (e.g. the full match, registration, or tournament record)

Before processing a payload, verify the signature header against your signing secret to confirm authenticity, then respond with HTTP 200 to acknowledge receipt.

Delivery logs and retries

Developer → Webhooks → [Webhook] → Logs — the Webhook Deliveries page — lists recent delivery attempts, their status, and response details for each one.

If your endpoint returns a non-200 status or times out, Tournament Suite automatically retries the delivery a limited number of times with increasing delay between attempts. You can also trigger retries yourself from the Deliveries page: Retry delivery on a single failed attempt, or Retry All Failed to requeue every failed delivery at once.

Delivery analytics

Developer → Webhooks → [Webhook] → Analytics shows delivery performance for that webhook over the last 7 days, including total deliveries, delivery rate, error rate, average response time, and a daily success/failure trend.

What happens next

With webhooks in place, your server receives events as they happen. To authenticate outbound API calls from your side, see API Keys. To post tournament updates directly to a Discord server, see Discord Integration.