Webhooks

Get notified instead of polling. Create subscriptions in the organizer area (Organization → API keys & webhooks): pick the events and the HTTPS endpoint; you receive a secret (whsec_…) that is shown once and is unique per subscription.

Events

competition.createdA competition was created (your own competitions) or became public (public subscriptions fire when it is published).
competition.updatedAny change: details, status, registration open/closed, finalization.
competition.cancelledThe competition was cancelled.
competition.startedThe competition moved to in progress.
competition.finalizedResults were validated; the payload includes the final standings.
standings.updatedA weigh-in changed the standings (bursts are merged into one event; only sent while the standings are publishable).

Scope own: events for your organization's competitions (including drafts). Scope public: events for every public competition, for external portals (at most 3 per organization). A ping event can be sent from the dashboard to test your endpoint.

Request

POST with a JSON body, headers X-Cupa-Event, X-Cupa-Delivery (= event id), X-Cupa-Attempt, and X-Cupa-Signature: t=<unix>,v1=<hmac> where v1 = HMAC-SHA256(secret, "<t>.<raw body>") in hex.

{
    "id": "5c1d6f0a-8d0b-4a8e-9f3e-2f8a6b0c9d11",
    "type": "competition.finalized",
    "created_at": "2027-05-02T18:30:00+00:00",
    "api_version": "v1",
    "data": {
        "competition": {
            "id": 42,
            "slug": "cupa-primaverii-2027",
            "title": "Cupa Primăverii",
            "status": "finalized",
            "…": "(same shape as GET /competitions/{id}, without long texts)"
        },
        "standings": {
            "state": "final",
            "general": [
                "…"
            ]
        }
    }
}

Delivery, retries and duplicates

Verifying signatures

PHP

<?php
$secret  = getenv('CUPA_WEBHOOK_SECRET');           // whsec_...
$body    = file_get_contents('php://input');          // the RAW body, not re-encoded JSON
$header  = $_SERVER['HTTP_X_CUPA_SIGNATURE'] ?? '';   // t=1700000000,v1=abcdef...
parse_str(str_replace(',', '&', $header), $p);
$ok = isset($p['t'], $p['v1'])
    && abs(time() - (int) $p['t']) <= 300                                   // reject replays older than 5 minutes
    && hash_equals(hash_hmac('sha256', $p['t'] . '.' . $body, $secret), $p['v1']);
if (!$ok) { http_response_code(400); exit; }
$event = json_decode($body, true);
// De-duplicate on $event['id'] (identical for every retry), then process and answer quickly:
http_response_code(204);

Node.js

import crypto from 'node:crypto';
import express from 'express';
const app = express();
app.post('/webhooks/cupa', express.raw({ type: 'application/json' }), (req, res) => {
  const [t, v1] = req.get('X-Cupa-Signature').split(',').map((p) => p.split('=')[1]);
  const expected = crypto.createHmac('sha256', process.env.CUPA_WEBHOOK_SECRET).update(`${t}.${req.body}`).digest('hex');
  const fresh = Math.abs(Date.now() / 1000 - Number(t)) <= 300;
  if (!fresh || !crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1))) return res.sendStatus(400);
  const event = JSON.parse(req.body); // dedupe on event.id
  res.sendStatus(204);
});

Python

import hmac, hashlib, os, time, json
from flask import Flask, request, abort

app = Flask(__name__)

@app.post("/webhooks/cupa")
def cupa():
    raw = request.get_data()                      # raw bytes
    parts = dict(p.split("=", 1) for p in request.headers["X-Cupa-Signature"].split(","))
    expected = hmac.new(os.environ["CUPA_WEBHOOK_SECRET"].encode(), f"{parts['t']}.".encode() + raw, hashlib.sha256).hexdigest()
    if abs(time.time() - int(parts["t"])) > 300 or not hmac.compare_digest(expected, parts["v1"]):
        abort(400)
    event = json.loads(raw)                       # dedupe on event["id"]
    return "", 204