Publica mensajes con un webhook

Inicio rápido

1. 1

   Crea el webhook

   En la app de escritorio, abre Manage Server → Webhooks en tu comunidad, crea un webhook, elige los canales en los que puede publicar y copia la URL de un canal. Tiene esta forma:

   urlCopiar

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

2. 2

   Envía un mensaje

   Firma el JSON con el secreto del webhook y envíalo con POST. Un webhook creado en la app de escritorio siempre tiene uno: cópialo de Webhook Secret en los ajustes del webhook.

   bashCopiar

   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

   Lee la respuesta

   La respuesta te da el id del mensaje y una callback_url para cambiar el mensaje más tarde.

   jsonCopiar

   {
     "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-..."
   }

Qué puedes enviar

Un mensaje es o bien la forma corta (texto con un título y un color) o bien una tarjeta completa, y cualquiera de las dos puede llevar botones y archivos. El nombre de arriba de la tarjeta es siempre el nombre del propio webhook. En los ajustes del webhook también decides si puede publicar imágenes y mencionar a personas.

Forma corta

Suficiente para la mayoría de las alertas.

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

Una tarjeta completa

Envía un message_container para una tarjeta con título enlazado, subtítulo, markdown, campos e imágenes. A través de un webhook, una tarjeta admite type, color, title, title_url, sub_title, description, fields, avatar_url, image_url, image_base64, images y los campos del loader. La píldora de estado, el distintivo, las estadísticas del diff y el razonamiento plegado son para respuestas a comandos. Todos los campos están en tarjetas de mensaje.

jsonCopiar

{
  "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 from CI

Build #1847 superado

Los 212 tests en verde en main.

Duration

2m 34s

Commit

1a2b3c4

09:12

Botones

Añade un array actions para poner botones bajo el mensaje. Cómo funcionan se explica en botones.

Archivos

Publica archivos de verdad con un mensaje: un log, un informe, una captura de pantalla. Se muestran como cualquier otro adjunto, como una fila de descarga o dentro del mensaje en el caso de imágenes, vídeo y audio. Un mensaje solo con archivos también vale: omite content y la tarjeta.

{
  "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"
    }
  ]
}

Por qué url solo acepta direcciones de mssgs

Una URL de webhook suele acabar pegada en otros paneles. Si se filtra, no debe permitir que alguien haga que la app de cada miembro descargue un archivo de un servidor que haya elegido él. Si tu archivo está en otro sitio, envíalo como content_base64 y mssgs lo aloja.

Una subida fallida no hace fallar el mensaje

Los archivos se comprueban de antemano pero se suben después. Si una subida falla, ese archivo se queda fuera y el resto del mensaje se publica igualmente, sin error: mejor perder el archivo que el informe. Si un archivo es importante, comprueba que ha llegado.

Un archivo desde la línea de comandos

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 @-

Firmar las peticiones

Un webhook con secreto solo acepta peticiones que demuestren que lo conocen, y un webhook creado en la app de escritorio siempre tiene uno (Webhook Secret en sus ajustes). Firma el cuerpo sin procesar de la petición con HMAC-SHA256 usando el secreto, y envía el digest hexadecimal en minúsculas en la cabecera X-Mssgs-Signature como 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
});

También se acepta la cabecera propia de GitHub X-Hub-Signature-256, así que un webhook de GitHub con el mismo secreto funciona tal cual. La firma no lleva marca de tiempo, así que no impide que una petición interceptada se vuelva a enviar: el secreto que de verdad importa sigue siendo la URL.

Respuestas y errores

Un mensaje publicado vuelve con su id y una callback_url para actualizarlo o borrarlo durante 30 minutos.

{
  "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}`);
}

Cuando el mensaje tiene botones, la respuesta incluye también una stream_url: un stream en directo de las respuestas, reacciones y pulsaciones de botón en ese mensaje, abierto durante 10 minutos, o una hora si envías "sse_event_extended_timeout": true. Consulta actualizaciones en directo.

Códigos de estado

Códigos de error

Errores de archivos

Límites

Las peticiones tienen un límite de frecuencia. Cuando recibas un 429, espera antes de volver a enviar, y agrupa en un solo mensaje las alertas que llegan en ráfagas.

GitHub, UniFi y App Store Connect

Apunta uno de estos servicios a una URL de webhook y mssgs lo reconoce y publica una tarjeta en condiciones, sin payload que escribir. Consulta integraciones. Estos reciben como respuesta {"success": true} y ninguna callback URL.