Brancher ton tournoi sur ton jeu ou ton site (API des tournois)

La finale de ta Bedwars Cup vient de se terminer sur ton serveur Minecraft. Luna gagne 2 à 1… et personne n'a besoin d'ouvrir Discord pour déclarer le score : le serveur de jeu l'envoie tout seul à Hurix, le tableau avance et le message de résultat part dans le salon. Avec l'API des tournois, ton serveur de jeu, ton site ou un simple script parlent directement à ton tournoi.

1. Comprendre le principe

Chaque tournoi a un onglet API. Tu y trouves deux outils :

• Les clés d'API : ton programme s'en sert pour agir sur le tournoi (lire le tableau, inscrire des joueurs, envoyer des scores, lancer le tournoi).
• Les webhooks : Hurix prévient ton programme dès qu'il se passe quelque chose (un match s'ouvre, un match se termine, un litige est ouvert…).

Ce qu'il faut retenir :

• Une clé ne fonctionne que pour son tournoi. Pour le tournoi suivant, tu crées une nouvelle clé.
• Les actions passent par le bot et suivent exactement les mêmes règles que le dashboard : statut du tournoi, format BO, tableau. Elles mettent aussi Discord à jour (fil du match, tableau, annonces, rôles de récompense).
• Les joueurs sont reconnus par leur identifiant Discord. Ton serveur de jeu doit donc savoir quel compte Discord correspond à quel joueur.

Pour ouvrir l'onglet : Engagement → Tournois, clique sur ton tournoi, puis sur l'onglet API. Il est réservé aux personnes qui peuvent modifier les tournois : les gestionnaires du serveur et les sous-utilisateurs qui ont la permission Tournois en Modifier.

2. Créer une clé

Dans la carte Clés d'API, clique sur Nouvelle clé.

1. Nom de la clé : dis où elle sert (« Serveur Bedwars », « Site de la ligue »…). Ce nom apparaît dans l'historique du tournoi à chaque action de la clé. 60 caractères au plus.
2. Permissions : n'active que ce dont ton programme a besoin.

| Permission | Ce que la clé peut faire | |---|---| | Lecture | Lire le tournoi, les participants, les matchs et le classement. | | Inscriptions | Inscrire ou retirer des participants. | | Résultats | Envoyer des scores et des forfaits, validés directement. | | Gestion | Ouvrir ou fermer les inscriptions, lancer et terminer le tournoi. |

Par défaut, Lecture et Résultats sont cochées : c'est ce qu'il faut à un serveur de jeu qui envoie les scores.

Clique sur Créer la clé. Hurix affiche la clé complète (elle commence par hxt_). Clique sur Copier et range-la tout de suite dans la configuration de ton programme, puis clique sur J'ai copié.

Tu peux avoir jusqu'à 10 clés actives par tournoi. Tu ne peux pas en créer pour un tournoi annulé.

3. Suivre et révoquer tes clés

Chaque clé de la liste affiche :

• son nom et le début de la clé (hxt_…), pour la reconnaître ;
• ses permissions ;
• qui l'a créée, quand, et sa dernière utilisation (ou « jamais utilisée »).

Une clé ne sert plus, ou tu crains qu'elle ait fuité ? Clique sur Révoquer puis confirme. Elle cesse de fonctionner tout de suite : les programmes qui l'utilisent reçoivent une erreur 401.

4. Envoyer un score automatiquement

La carte Démarrage rapide rassemble ce dont ton développeur a besoin :

• l'adresse de l'API : https://hurix.xyz/api/v1 ;
• l'identifiant du tournoi (le nombre à mettre dans les adresses) ;
• un exemple prêt à copier pour envoyer un résultat.

À la fin d'une partie, ton serveur de jeu envoie les deux comptes Discord et leurs scores. Hurix retrouve tout seul le match en cours entre ces deux joueurs et remet les scores dans le bon ordre :

curl -X POST https://hurix.xyz/api/v1/tournaments/42/results \
  -H "Authorization: Bearer hxt_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: partie-4821" \
  -d '{"players":["123456789012345678","234567890123456789"],"scores":[2,1]}'

Remplace 42 par l'identifiant de ton tournoi et hxt_… par ta clé. Tu peux ajouter "note" (par exemple "Partie #4821") : elle apparaît dans l'historique.

Pour lire les matchs à jouer maintenant (clé avec Lecture) :

curl https://hurix.xyz/api/v1/tournaments/42/matches?status=open \
  -H "Authorization: Bearer hxt_…"

Quelques règles utiles :

• `Idempotency-Key` : donne une valeur unique par partie (son numéro, par exemple). Si ton serveur renvoie la même requête après une coupure réseau, le score ne compte qu'une fois.
• Un score impossible pour le format (3–0 en BO3), un match pas encore ouvert ou un match dont la suite est déjà jouée sont refusés, avec un message clair.
• 120 requêtes par minute et par clé. Au-delà, l'API répond 429 et indique dans combien de secondes réessayer.

La documentation complète (forfaits, score d'un match précis, inscriptions, lancement du tournoi, codes d'erreur) est sur hurix.xyz/developers/tournaments, ou via le bouton Documentation complète.

5. Ce qui se passe quand l'API envoie un score

Le résultat est validé aussitôt, sans confirmation des joueurs. Comme pour une saisie du staff :

• le tableau avance et le match suivant s'ouvre dès que les deux joueurs sont connus ;
• le panneau du match est mis à jour et, si tu as choisi un salon des résultats dans les paramètres du module, le message de résultat y est publié.

Dans l'onglet Historique du tournoi, l'action est signée « API · nom de la clé », avec la note éventuelle. Tu sais toujours quel programme a fait quoi.

6. Ajouter un webhook

Un webhook, c'est une adresse de ton site ou de ton serveur que Hurix appelle à chaque événement du tournoi. Par exemple : ton serveur Minecraft apprend qu'un match vient de s'ouvrir et téléporte les deux joueurs dans l'arène.

Dans la carte Webhooks, clique sur Ajouter un webhook :

1. Adresse (https) : un nom de domaine public uniquement, pas d'adresse IP ni de réseau local.
2. Événements : coche ceux qui t'intéressent (Tout cocher pour tous).

| Événement | Quand Hurix l'envoie | |---|---| | Match ouvert · match.opened | Un match peut être joué. | | Match terminé · match.completed | Un match a son résultat. | | Litige ouvert · match.disputed | Un joueur conteste un score. | | Inscriptions ouvertes / fermées | Les inscriptions changent d'état. | | Tournoi lancé / terminé / annulé | Le tournoi change d'état. | | Nouvel inscrit · Désinscription | Un joueur s'inscrit ou se retire. | | Participant exclu · Joueur remplacé | Le staff exclut ou remplace un joueur. |

Clique sur Ajouter. Hurix affiche le secret de signature (il commence par whsec_) : copie-le pour ton développeur.

Tu peux avoir jusqu'à 5 webhooks par tournoi.

Vérifier la signature (pour ton développeur)

Chaque requête est un POST en JSON avec les en-têtes X-Hurix-Event, X-Hurix-Delivery, X-Hurix-Timestamp et X-Hurix-Signature. La signature vaut sha256= suivi du HMAC-SHA256 de horodatage.corps avec le secret. Exemple en PHP, tiré de la documentation :

<?php
$body = file_get_contents('php://input');
$timestamp = $_SERVER['HTTP_X_HURIX_TIMESTAMP'] ?? '';
$signature = $_SERVER['HTTP_X_HURIX_SIGNATURE'] ?? '';
$expected = 'sha256=' . hash_hmac('sha256', $timestamp . '.' . $body, getenv('HURIX_WEBHOOK_SECRET'));
if (abs(time() - (int) $timestamp) > 300 || !hash_equals($expected, $signature)) {
    http_response_code(401);
    exit;
}
$event = json_decode($body, true);
http_response_code(200);

La documentation donne aussi la version Node.js et le contenu exact de chaque événement.

7. Tester et surveiller tes webhooks

Chaque webhook de la liste affiche son état :

• Actif : tout va bien ;
• En échec : les derniers envois n'ont pas abouti (avec l'erreur, par exemple « réponse HTTP 502 ») ;
• Désactivé : tu l'as mis en pause avec l'interrupteur ;
• Coupé après trop d'échecs : Hurix l'a arrêté après 20 échecs d'affilée.

Les boutons de chaque ligne :

• l'interrupteur met le webhook en pause ou le réactive (la réactivation remet le compteur d'échecs à zéro) ;
• Tester envoie un événement ping : il part dans les 20 secondes ;
• la corbeille supprime le webhook (les envois en attente sont abandonnés) ;
• la flèche déplie ses événements et ses derniers envois : Reçu, En attente ou Abandonné, avec le nombre d'essais.

Si ton adresse ne répond pas par un code 2xx en moins de 8 secondes, Hurix réessaie après 1 min, 5 min, 30 min, 2 h, 6 h puis 24 h, et abandonne. Les envois partent au plus tard 20 secondes après l'événement.

🔒 Sécurité

• Une clé par usage : une pour le serveur de jeu, une pour le site. Si l'une fuit, tu ne révoques qu'elle.
• Le moins de permissions possible : un site qui affiche le tableau n'a besoin que de Lecture.
• Jamais dans une page web ni dans un fichier public (dépôt GitHub, capture d'écran, salon Discord).
• Vérifie toujours la signature des webhooks et refuse un horodatage de plus de 5 minutes.
• Chaque création ou révocation de clé, et chaque ajout ou suppression de webhook, est inscrit dans l'historique du tournoi.

Tu veux aussi lire les rôles, boosts ou niveaux de tes membres depuis ton plugin ? Découvre le tutoriel Connecter tes outils aux membres de ton serveur.

Questions fréquentes

Faut-il savoir programmer ? Pour créer les clés et les webhooks, non : tout se fait dans le dashboard. Pour brancher ton serveur de jeu ou ton site, il faut un petit développement (plugin, script) : donne à ton développeur la clé et le lien de la documentation.

Un joueur peut-il contester un score envoyé par l'API ? Le score est validé directement, sans confirmation. Si un joueur pense qu'il est faux, il prévient le staff, qui corrige ou fait rejouer le match depuis l'onglet Matchs.

Ma clé répond 404 sur un autre tournoi, c'est normal ? Oui. Une clé ne fonctionne que pour le tournoi où elle a été créée. Crée une clé dans l'onglet API de chaque tournoi.

Ma clé répond 403 « missing_scope ». Il lui manque la permission nécessaire (par exemple Résultats pour envoyer un score). Crée une nouvelle clé avec la bonne permission et révoque l'ancienne.

Je peux changer les événements d'un webhook ? Pas depuis le dashboard : supprime-le et ajoute-en un nouveau avec les bons événements (pense à donner le nouveau secret à ton développeur).

Les limites dépendent-elles de mon offre ? Non. Les limites de l'API (10 clés et 5 webhooks par tournoi, 120 requêtes par minute et par clé) sont les mêmes pour tous les serveurs : elles protègent le bot et Discord.