Publier des messages avec un webhook

Démarrage rapide

1. 1

   Crée le webhook

   Dans l’application de bureau, ouvre Gérer le serveur → Webhooks dans ta communauté, crée un webhook, choisis les salons où il peut publier et copie l’URL d’un salon. Elle a cette forme :

   urlCopier

   https://mss.gs/api/v1/webhook/{webhook_guid}/{token}/{channel_guid}

2. 2

   Envoie un message

   Signe le JSON avec le secret du webhook et envoie-le en POST. Un webhook créé dans l’application de bureau en a toujours un : copie-le depuis Secret du webhook dans les réglages du webhook.

   bashCopier

   BODY='{"content": "Build #1847 passed on main"}'
   SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$MSSGS_WEBHOOK_SECRET" | sed 's/^.* //')
   
   curl -X POST "$MSSGS_WEBHOOK_URL" \
     -H "Content-Type: application/json" \
     -H "X-Mssgs-Signature: sha256=$SIG" \
     -d "$BODY"

3. 3

   Lis la réponse

   La réponse te donne l’id du message, et une callback_url pour modifier le message plus tard.

   jsonCopier

   {
     "success": true,
     "message_id": "aZZ1a2b-...",
     "callback_url": "https://mss.gs/api/v1/trigger-callback/8f14e45f-...",
     "stream_url": "https://mss.gs/api/v1/instant/6b1e...c0?token=a1b2c3d4-..."
   }

Ce que tu peux envoyer

Un message prend soit la forme courte (du texte avec un titre et une couleur), soit celle d’une carte complète, et les deux peuvent porter des boutons et des fichiers. Le nom en haut de la carte est toujours celui du webhook. Dans les réglages du webhook, tu décides aussi s’il peut publier des images et mentionner des personnes.

Forme courte

Suffisante pour la plupart des alertes.

{
  "content": "Server backup completed at 03:00 UTC",
  "color": "green",
  "title": "Backup Bot"
}

Une carte complète

Envoie un message_container pour une carte avec un titre cliquable, un sous-titre, du markdown, des champs et des images. Via un webhook, une carte accepte type, color, title, title_url, sub_title, description, fields, avatar_url, image_url, image_base64, images et les champs de chargement. La pastille de statut, le badge, les stats de diff et le raisonnement replié sont réservés aux réponses de commande. Chaque champ est décrit sur cartes de message.

jsonCopier

{
  "message_container": {
    "type": "embed_message",
    "color": "green",
    "title": "Build #1847 passed",
    "title_url": "https://ci.example.com/builds/1847",
    "description": "All 212 tests green on **main**.",
    "fields": [
      { "field": "Duration", "value": "2m 34s" },
      { "field": "Commit", "value": "1a2b3c4" }
    ]
  }
}

#deploys

Message de CI

Build #1847 réussi

Les 212 tests sont au vert sur main.

Duration

2m 34s

Commit

1a2b3c4

09:12

Boutons

Ajoute un tableau actions pour placer des boutons sous le message. Leur fonctionnement est expliqué sur boutons.

Fichiers

Publie de vrais fichiers avec un message : un log, un rapport, une capture d’écran. Ils s’affichent comme n’importe quelle pièce jointe, en ligne de téléchargement, ou intégrés pour les images, la vidéo et l’audio. Un message composé uniquement de fichiers est valide : omets content et la carte.

{
  "message_container": {
    "color": "orange",
    "title": "Log dump: ios",
    "description": "DMs stopped arriving after switching networks"
  },
  "attachments": [
    {
      "name": "mssgs-logs-20260803-141205.log",
      "content_base64": "MjAyNi0wOC0wMyAxNDoxMjowNSBbV1NdIGNvbm5lY3RlZAo=",
      "mime_type": "text/plain"
    }
  ]
}

Pourquoi url n’accepte que des adresses mssgs

Une URL de webhook finit souvent collée dans d’autres tableaux de bord. Une URL qui a fuité ne doit pas permettre à quelqu’un de faire télécharger à l’application de chaque membre un fichier depuis un serveur de son choix. Si ton fichier se trouve ailleurs, envoie-le en content_base64 et mssgs l’héberge.

Un envoi raté ne fait pas échouer le message

Les fichiers sont vérifiés d’abord, mais envoyés ensuite. Si un envoi échoue, ce fichier est laissé de côté et le reste du message est quand même publié, sans erreur : mieux vaut perdre le fichier que le rapport. Si un fichier compte, vérifie qu’il est bien arrivé.

Un fichier depuis la ligne de commande

BODY='{"attachments":[{"name":"report.csv","content_base64":"'"$(base64 < report.csv | tr -d '\n')"'","mime_type":"text/csv"}]}'
SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$MSSGS_WEBHOOK_SECRET" | sed 's/^.* //')

printf '%s' "$BODY" | curl -sS -X POST "$MSSGS_WEBHOOK_URL" \
  -H 'Content-Type: application/json' \
  -H "X-Mssgs-Signature: sha256=$SIG" \
  --data-binary @-

Signer les requêtes

Un webhook doté d’un secret n’accepte que les requêtes qui prouvent le connaître, et un webhook créé dans l’application de bureau en a toujours un (Secret du webhook dans ses réglages). Signe le corps brut de la requête en HMAC-SHA256 avec le secret, et envoie le condensé hexadécimal en minuscules dans l’en-tête X-Mssgs-Signature, sous la forme sha256=<hex>.

import crypto from 'node:crypto';

const body = JSON.stringify({ content: 'Deploy finished' });
const signature = crypto.createHmac('sha256', process.env.MSSGS_WEBHOOK_SECRET)
  .update(body)
  .digest('hex');

await fetch(process.env.MSSGS_WEBHOOK_URL, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Mssgs-Signature': `sha256=${signature}`
  },
  body
});

L’en-tête X-Hub-Signature-256 de GitHub est accepté aussi, donc un webhook GitHub avec le même secret fonctionne tel quel. La signature ne contient pas d’horodatage : elle n’empêche donc pas qu’une requête interceptée soit renvoyée. C’est l’URL qui reste le secret qui compte.

Réponses et erreurs

Un message publié revient avec son id et une callback_url pour le mettre à jour ou le supprimer pendant 30 minutes.

{
  "success": true,
  "message_id": "aZZ1a2b-...",
  "callback_url": "https://mss.gs/api/v1/trigger-callback/8f14e45f-...",
  "stream_url": "https://mss.gs/api/v1/instant/6b1e...c0?token=a1b2c3d4-..."
}

HTTP/1.1 200 OK
Content-Type: application/json

{ "error": "ATTACHMENT_TOO_LARGE" }

const res = await fetch(webhookUrl, { method: 'POST', headers, body });
const reply = await res.json().catch(() => null);

// A rejected payload still comes back as 200: read the body.
if (!res.ok || (reply && reply.error)) {
  throw new Error(`webhook rejected: ${reply?.error ?? res.status}`);
}

Quand le message a des boutons, la réponse contient aussi une stream_url : un flux en direct des réponses, réactions et appuis sur les boutons de ce message, ouvert pendant 10 minutes, ou une heure si tu envoies "sse_event_extended_timeout": true. Voir mises à jour en direct.

Codes de statut

Codes d’erreur

Erreurs de fichiers

Limites

Les requêtes sont soumises à une limite de débit. Quand tu reçois un 429, attends avant de renvoyer, et regroupe en un seul message les alertes qui arrivent en rafale.

GitHub, UniFi et App Store Connect

Fais pointer l’un de ces services vers une URL de webhook : mssgs le reconnaît et publie une vraie carte, sans payload à écrire. Voir intégrations. Ces services reçoivent en réponse {"success": true}, sans URL de callback.