Portail développeurs
Expérimental La plateforme de bots et d'apps est en développement actif. La prise en charge des serveurs auto-hébergés est arrivée le 13/08/2026, avec moins de fonctionnalités que le 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 de 8 caractères}.{aléatoire en base64}

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 gérez, 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 est passée 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 est passée 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} reproduisent Discord.
  • Surcharge du nom 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 à l’administration d’un serveur. Supprimer le salon ne supprime pas l’enregistrement du webhook ; l’exécution suivante renvoie 404 à cause de la jointure sur le salon dans la requête.
  • Pas de surcharge de username / avatar_url par requête. L’identité est fixée à l’utilisateur bot.
  • Aucun plafond 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’attaquez pas l’endpoint en boucles serrées.
  • Serveurs auto-hébergés : les webhooks ne sont pas relayés vers les instances auto-hébergées. Tous les endpoints de webhook renvoient 404 pour une guild auto-hébergée. Voir la documentation auto-hébergée.

← Retour à la documentation