Pexxoo

Dernière mise à jour :

Webhooks entrants

Poste des messages dans un salon depuis un outil externe : URL, format JSON, exemples et erreurs.

Un webhook entrant permet à un outil externe (intégration continue, formulaire, script de supervision, flux…) de poster un message dans un salon de ton serveur avec une simple requête HTTP, sans compte ni bot.

Créer un webhook#

  1. Ouvre les paramètres du serveur, onglet « Webhooks » (permission « Gérer le serveur » requise).
  2. Donne un nom au webhook et choisis le salon cible (un salon qui n'est pas vocal).
  3. Clique sur « Créer » : l'URL complète s'affiche une seule fois. Copie-la tout de suite.

Un serveur peut avoir 20 webhooks au maximum.

Format de l'URL#

text
POST <URL_API>/api/hooks/<serverId>/<token>

<URL_API> est l'adresse de l'API de ton instance Pexxoo. Le plus simple est de copier l'URL complète affichée à la création : elle contient déjà tout.

Le jeton fait office de mot de passe : il n'y a pas d'autre en-tête d'authentification à envoyer.

Format de la requête#

Envoie un corps JSON (Content-Type: application/json, en UTF-8).

JSON
{
  "content": "Déploiement terminé ✅",
  "username": "CI"
}
ChampTypeDescription
contenttexteTexte du message, 2000 caractères maximum. Peut être vide si tu envoies des embeds.
usernametexte, facultatifNom affiché au-dessus du message, de 1 à 80 caractères. S'il est absent, c'est le nom du webhook qui est affiché.
embedsliste, facultatif5 cartes de lien au maximum.

Embeds (cartes de lien)

ChampDescription
urlObligatoire. Adresse http ou https, 500 caractères maximum.
titleFacultatif, 200 caractères maximum.
descriptionFacultatif, 500 caractères maximum.
imageFacultatif. Adresse http ou https d'une image, 500 caractères maximum.

Exemples#

Remplace l'URL par celle de ton webhook.

cURL
curl -X POST "https://api.exemple.com/api/hooks/SERVER_ID/TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"content":"Déploiement terminé ✅","username":"CI"}'

Réponses et codes d'erreur#

En cas de succès, l'API répond 201 avec l'identifiant du message :

201 Created
{ "ok": true, "id": "k3x9a1" }

Les erreurs ont toutes la même forme :

JSON
{ "error": { "code": "invalid_input", "message": "content: …" } }
Code HTTPSignification
400Requête invalide : champ trop long, type incorrect, URL d'embed invalide (code invalid_input), ou message vide (code empty).
401Jamais renvoyé : un jeton absent, faux ou périmé donne volontairement un 404 (voir ci-dessous).
404Webhook introuvable : jeton inconnu ou régénéré, webhook supprimé, serveur inexistant, ou salon cible supprimé. La réponse est identique dans tous ces cas, pour ne rien révéler à une personne qui devine des URL.
429Trop de requêtes (code rate_limited). Attends un peu avant de réessayer.

Limites#

  • 2000 caractères maximum dans le champ content.
  • 30 messages par minute et par webhook.
  • 60 requêtes par minute et par adresse IP, tous webhooks confondus.
  • Un message Pexxoo fait 4000 caractères au maximum : le nom affiché est ajouté au texte.

Sécurité du jeton#

  • Garde l'URL dans un coffre à secrets (variables secrètes de ton outil de CI, gestionnaire de mots de passe), jamais dans le code source.
  • Un webhook = un usage : crée-en un par outil pour pouvoir en révoquer un sans toucher aux autres.
  • Si l'URL a fuité, régénère le jeton ou supprime le webhook.

Régénérer le jeton#

Comme l'URL n'est plus récupérable après la création, un webhook existant dont tu as perdu l'URL peut recevoir un nouveau jeton : dans l'onglet « Webhooks », clique sur « Régénérer le jeton ».

  • L'ancienne URL cesse de fonctionner immédiatement.
  • La nouvelle URL n'est affichée qu'une seule fois.
  • L'action est enregistrée dans le journal d'audit du serveur.

Le bouton « Envoyer un message de test » poste « ✅ Test réussi » dans le salon cible pour vérifier que tout est branché.

Voir aussi#