Portail développeurs
Expérimental La plateforme de bots & d’apps est en développement actif. Les serveurs auto-hébergés font tourner les bots, les commandes slash et les composants de message, avec quelques différences par rapport au cloud. Voir ce qui est pris en charge.
← Docs

Webhooks d’app

Un webhook d’app est une URL par salon vers laquelle votre runner CI, votre outil de supervision ou un service externe peut faire un POST afin de déposer un message dans un salon GameVox. Aucune session gateway requise. Les messages sont publiés sous votre utilisateur bot, avec son avatar et son nom.

Limites

  • 50 webhooks par application.
  • Nom : 1–80 caractères.
  • Contenu : 1–4000 caractères par message.
  • Un webhook = un salon. Créer un webhook nécessite la permission manage_server sur le serveur du salon.

Format du jeton

WH.{préfixe 8 car.}.{base64 aléatoire}

exemple: WH.aB7xZ2k1.q9F7v1NkN3J2Wm8L6PpV5cU0Yr1zQbXa

Le jeton complet est affiché exactement une fois, à la création. Nous ne conservons que le hash bcrypt, le préfixe et les 4 derniers caractères pour l’affichage. Si vous perdez un jeton, supprimez le webhook et créez-en un nouveau.

Créer un webhook (portail)

Ouvrez votre application → onglet Webhooks → Nouveau webhook. Choisissez un serveur que vous pouvez gérer, choisissez un salon, donnez-lui un nom. La fenêtre affiche le jeton complet et l’URL d’exécution prête à coller. Copiez-la avant de fermer ; le portail ne l’affichera plus jamais.

Endpoints

Deux modes d’authentification : jeton de bot pour la gestion, jeton dans l’URL pour l’exécution.

Authentification par jeton de bot (gestion)

GET    /channels/{channel.id}/webhooks
POST   /channels/{channel.id}/webhooks
GET    /guilds/{guild.id}/webhooks
GET    /webhooks/{webhook.id}
PATCH  /webhooks/{webhook.id}
DELETE /webhooks/{webhook.id}

Authentification par jeton dans l’URL (exécution + modification)

POST   /webhooks/{webhook.id}/{token}
GET    /webhooks/{webhook.id}/{token}
PATCH  /webhooks/{webhook.id}/{token}
DELETE /webhooks/{webhook.id}/{token}
PATCH  /webhooks/{webhook.id}/{token}/messages/{message.id}
DELETE /webhooks/{webhook.id}/{token}/messages/{message.id}

Pour les routes à jeton dans l’URL, il n’y a pas d’en-tête Authorization. Le jeton du chemin est l’authentification. Traitez l’URL comme un secret.

Requête d’exécution

Corps JSON :

POST https://api.gamevox.com/webhooks/{webhook.id}/{token}
Content-Type: application/json

{
  "content": "La build #4811 a réussi en production.",
  "embeds": [
    {
      "title": "CI au vert",
      "url": "https://ci.example.com/builds/4811",
      "description": "42 tests, 0 échec.",
      "color": 3066993
    }
  ]
}

Corps multipart/form-data (pour les pièces jointes) :

Content-Type: multipart/form-data; boundary=xyz

--xyz
Content-Disposition: form-data; name="payload_json"

{ "content": "Voir la capture", "embeds": [ ... ] }
--xyz
Content-Disposition: form-data; name="files[0]"; filename="crash.png"
Content-Type: image/png

...binary...
--xyz--

Réponse (pour les deux types de contenu) :

{
  "id": "1199283740192847400",
  "channel_id": "1199283740192847000",
  "content": "La build #4811 a réussi en production.",
  "embeds": [ ... ],
  "attachments": [ ... ],
  "timestamp": "2026-05-21T15:42:09Z"
}

Ce qui est pris en charge

  • Contenu : texte brut, 1–4000 caractères.
  • Embeds : forme d’embed Discord complète (title, description, url, color, timestamp, footer, image, thumbnail, author, fields). Plusieurs embeds par message sont autorisés.
  • Pièces jointes : envoyez des fichiers en multipart/form-data avec une partie payload_json ; la réponse contient des URL de CDN.
  • Réponse ciblée : passez message_reference dans payload_json.
  • ?wait=true : implicite ; la réponse est toujours le message résolu.
  • Modifier / supprimer : PATCH / DELETE sur /webhooks/{id}/{token}/messages/{message.id} fonctionnent comme sur Discord.
  • Surcharge du nom d’utilisateur ou de l’avatar : non prise en charge. Les messages sont toujours publiés sous l’utilisateur bot de l’application.

Erreurs

  • 401 : jeton manquant, mal formé ou non concordant.
  • 404 : webhook supprimé, ou id inexistant.
  • 400 : content vide sans embeds ni pièces jointes, ou content de plus de 4000 caractères.
  • 405 : verbe non pris en charge sur cette route.
  • 413 : la pièce jointe dépasse la limite de taille par fichier.

Rotation

Il n’y a pas d’endpoint de rotation sur place en v1. Supprimez le webhook et créez-en un nouveau. L’ancien jeton cesse de fonctionner immédiatement à la suppression (le chemin d’exécution exclut les lignes supprimées logiquement).

Différences avec Discord

  • Les webhooks appartiennent à l’application, pas à un administrateur de serveur. Supprimer un salon cloud supprime ses webhooks. Sur un serveur auto-hébergé, l’enregistrement du webhook survit à la suppression du salon, et son exécution échoue car l’instance n’a plus le salon.
  • Pas de surcharge de username / avatar_url par requête. L’identité est fixée à l’utilisateur bot.
  • Aucun plafond de webhooks par salon n’est appliqué ; le plafond est par application (50).
  • L’authentification est vérifiée avec bcrypt, la comparaison du jeton est donc volontairement lente. N’appelez pas l’endpoint en boucle serrée.
  • Serveurs auto-hébergés : les webhooks fonctionnent comme dans le cloud. Les enregistrements des webhooks vivent dans le cloud, la permission de les gérer est vérifiée par l’instance du client, et les messages produits par l’exécution sont écrits dans le salon auto-hébergé. Voir la documentation auto-hébergée.

← Retour à la documentation