Quand utiliser un webhook
Utilisez un webhook pour les notifications de build, les événements de services externes ou les mises à jour. Il publie dans un salon textuel présélectionné. Pour lire les messages, gérer commandes et boutons ou réagir à des événements, utilisez un bot.
Créer un webhook
Ouvrez les paramètres du salon textuel → Webhooks · messages automatisés. Créer et supprimer des webhooks exige MANAGE_CHANNELS. Enregistrez le chemin et le jeton renvoyés : le secret n’est affiché qu’une fois et seul son empreinte est stockée.
| Jeton de compte | Opération |
|---|---|
| GET /api/channels/:channelId/webhooks | Lister les webhooks. |
| POST /api/channels/:channelId/webhooks | {name, author_name?, avatar_url?} → 201 {webhook, token, path}. |
| DELETE /api/channels/:channelId/webhooks/:id | Supprimer un webhook. |
L’adresse et l’identifiant appartiennent à l’API de l’hébergeur du salon. Les webhooks ne prennent pas en charge les messages directs, les groupes ni les espaces publics.
Envoyer
POST /api/webhooks/:id/execute
Authorization: Bearer <WEBHOOK_TOKEN>
Content-Type: application/json
{ "embeds": [{
"title": "Build prêt",
"description": "La version est prête à être vérifiée.",
"color": 5793266,
"fields": [{ "name": "Statut", "value": "Prêt", "inline": true }]
}] }{"content":"Texte"} est également accepté, jusqu’à 2000 caractères. Jusqu’à 10 embeds pour 6000 caractères au total. Lorsque du texte accompagne des embeds, il occupe un emplacement d’embed. Une réponse 201 réussie contient l’id du message et channel_id. Le salon est défini dans la configuration, pas dans le corps de la requête.
Limites et sécurité
- Une requête acceptée par webhook toutes les 2 secondes. Sur 429, utilisez Retry-After: 2.
- L’auteur et l’avatar sont définis à la création du webhook, pas par un expéditeur quelconque. Les messages sont marqués comme webhooks.
- Les permissions du créateur sont vérifiées à l’envoi. Une perte de permissions peut produire 403.
- Ne répétez pas une requête au résultat inconnu sans vérifier : l’idempotence n’est pas implémentée.
- Envoyez le secret dans Authorization, pas dans l’URL. Supprimez et recréez un webhook si son secret fuit.
- Évitez les données personnelles dans les notifications et les URL d’images externes.