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.created | A competition was created (your own competitions) or became public (public subscriptions fire when it is published). |
competition.updated | Any change: details, status, registration open/closed, finalization. |
competition.cancelled | The competition was cancelled. |
competition.started | The competition moved to in progress. |
competition.finalized | Results were validated; the payload includes the final standings. |
standings.updated | A 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
- Answer with any
2xxwithin 8 seconds. Anything else (or a timeout) is retried with back-off after 1 min, 5 min, 30 min, 2 h, 6 h, 24 h; after 7 attempts the delivery is marked dead and can be retried from the dashboard.410 Gonedisables the subscription. - Delivery is at least once. The event
idis identical across retries: store it and ignore repeats. Order is not guaranteed; usedata.competition.updated_atto ignore stale events. - Redirects are not followed. Endpoints must be public HTTPS hosts on port 443, 8443 or 8080; private, loopback and link-local addresses are refused, both when saving and at delivery time.
- Always verify the signature and reject timestamps older than 5 minutes.
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