---
title: "Webhook-uri: postează mesaje într-un canal mssgs"
description: "Trimite un mesaj sau un card într-un canal mssgs din CI, monitorizare sau orice script, cu o singură cerere HTTP. Formate, fișiere, semnare, erori și limite."
canonical: https://docs.mss.gs/ro/webhooks
language: ro
---

# Postează mesaje cu un webhook

Un webhook este un URL care postează în comunitatea ta. Trimite-i JSON din orice poate face o cerere HTTP, de exemplu CI, monitorizare, un cron job sau un script, iar mesajul apare în canal.

## Ce poți face

- **Postează text sau un card** Text simplu sau un card cu titlu, culoare, markdown, câmpuri și imagini.

- **Atașează fișiere** Până la cinci fișiere per mesaj: loguri, rapoarte, capturi de ecran.

- **Adaugă butoane** Linkuri sau butoane care schimbă cardul ori ajung la serviciul tău.

- **Modifică-l mai târziu** Răspunsul conține un URL de callback pentru a actualiza sau șterge mesajul.

În aplicație

#### Build-ul #1847 a trecut

O cerere din CI, un card în #deploys. Numele din partea de sus este numele pe care i l-ai dat webhook-ului.

- [Start rapid](#quick-start)

- [Ce poți trimite](#format)

- [Fișiere](#attachments)

- [Semnare](#signing)

- [Răspunsuri și erori](#responses)

- [Limite](#limits)

- [GitHub, UniFi, App Store](#special)

## Start rapid

### Creează webhook-ul

În aplicația desktop, deschide în comunitatea ta **Manage Server → Webhooks**, creează un webhook, alege canalele în care are voie să posteze și copiază URL-ul pentru un canal. Arată așa:

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

### Trimite un mesaj

Semnează JSON-ul cu secretul webhook-ului și trimite-l cu POST. Un webhook creat în aplicația desktop are întotdeauna unul: copiază-l din **Webhook Secret**, în setările webhook-ului.

```bash
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"
```

### Citește răspunsul

Răspunsul îți dă id-ul mesajului și un callback_url cu care poți modifica mesajul mai târziu.

```json
{
  "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 poți trimite

Un mesaj este fie forma scurtă (text cu un titlu și o culoare), fie un card complet, iar oricare dintre ele poate avea butoane și fișiere. Numele din partea de sus a cardului este întotdeauna numele webhook-ului. Tot în setările webhook-ului decizi dacă poate posta imagini și menționa oameni.

### Forma scurtă

Suficientă pentru majoritatea alertelor.

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

| Câmp | Tip | Ce face |
| --- | --- | --- |
| content | string | Textul mesajului. Obligatoriu, cu excepția cazului în care trimiți un card sau fișiere. |
| color | string | blue (implicit), green , orange , red , yellow sau purple . |
| title | string | Un titlu deasupra textului. Implicit, numele webhook-ului. |

### Un card complet

Trimite un message_container pentru un card cu titlu cu link, subtitlu, markdown, câmpuri și imagini. Printr-un webhook, un card acceptă type , color , title , title_url , sub_title , description , fields , avatar_url , image_url , image_base64 , images și câmpurile de loader. Eticheta de status, badge-ul, statisticile de diff și raționamentul pliat sunt pentru răspunsurile la comenzi. Toate câmpurile sunt descrise la [carduri de mesaj](https://docs.mss.gs/ro/bots).

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

#### Build-ul #1847 a trecut

### Butoane

Adaugă un array actions ca să pui butoane sub mesaj. Cum funcționează afli la [butoane](https://docs.mss.gs/ro/buttons).

## Fișiere

Postează fișiere reale împreună cu un mesaj: un log, un raport, o captură de ecran. Apar ca orice alt atașament, ca rând de descărcare sau direct în mesaj pentru imagini, video și audio. Un mesaj doar cu fișiere este în regulă: lasă deoparte content și cardul.

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

| Câmp | Tip | Ce face |
| --- | --- | --- |
| name | string | Numele cu care se descarcă fișierul. Obligatoriu. O cale este redusă la ultima ei parte. |
| content_base64 | string | Octeții fișierului în base64, simplu sau ca URI data: . mssgs stochează fișierul și păstrează doar un link în mesaj. |
| mime_type | string | Tipul de conținut al content_base64 . Implicit text/plain . |
| url | string | Un fișier găzduit deja pe mssgs: o cale /static/... sau un URL https://mss.gs/... . |

| Limită | Valoare |
| --- | --- |
| Fișiere per mesaj | **5** |
| Dimensiune per fișier, după decodare | **8 MB** |
| Numele fișierului | 200 de caractere |
| Întreaga cerere | Aproximativ 10 MB. Base64 face un fișier cu o treime mai mare, așa că un singur fișier de peste aproximativ 7 MB nu încape. |

### De ce url acceptă doar adrese mssgs

Un URL de webhook ajunge adesea lipit în alte dashboard-uri. Dacă scapă, nu trebuie să-i permită cuiva să facă aplicația fiecărui membru să descarce un fișier de pe un server ales de el. Dacă fișierul tău se află în altă parte, trimite-l ca content_base64 , iar mssgs îl găzduiește.

### O încărcare eșuată nu blochează mesajul

Fișierele sunt verificate de la început, dar încărcate după aceea. Dacă o încărcare eșuează, fișierul respectiv este omis, iar restul mesajului se postează oricum, fără eroare: e mai bine să pierzi fișierul decât raportul. Dacă un fișier contează, verifică dacă a ajuns.

### Un fișier din linia de comandă

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

## Semnarea cererilor

Un webhook cu secret acceptă doar cereri care dovedesc că îl cunosc, iar un webhook creat în aplicația desktop are întotdeauna unul (**Webhook Secret** în setările lui). Semnează corpul brut al cererii cu HMAC-SHA256 folosind secretul și trimite digestul hex cu litere mici în antetul X-Mssgs-Signature , sub forma sha256=<hex> .

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

Este acceptat și antetul propriu al GitHub, X-Hub-Signature-256 , așa că un webhook GitHub cu același secret funcționează ca atare. Semnătura nu are timestamp, deci nu împiedică retrimiterea unei cereri interceptate: URL-ul rămâne secretul care contează.

## Răspunsuri și erori

Un mesaj postat se întoarce cu id-ul lui și un callback_url cu care îl poți actualiza sau șterge timp de 30 de minute.

```json
{
  "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
HTTP/1.1 200 OK
Content-Type: application/json

{ "error": "ATTACHMENT_TOO_LARGE" }
```

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

Când mesajul are butoane, răspunsul conține și un stream_url : un flux live cu răspunsurile, reacțiile și apăsările de butoane de pe acel mesaj, deschis 10 minute sau o oră dacă trimiți "sse_event_extended_timeout": true . Vezi [actualizări live](https://docs.mss.gs/ro/live-updates).

### Coduri de status

| Status | Când |
| --- | --- |
| 401 | Webhook-ul are un secret, iar semnătura lipsește sau este greșită. |
| 403 | Acest webhook nu are voie să posteze în acel canal. |
| 404 | Nu există niciun webhook la acest URL. |
| 413 | Cererea este prea mare. |
| 429 | Prea multe cereri. Încetinește și încearcă din nou. |
| 502 | Mesajul nu a putut fi livrat. Încearcă din nou. |

### Coduri de eroare

| Cod | Semnificație |
| --- | --- |
| MISSING_CONTENT | Nimic de postat: niciun text, niciun card și niciun fișier. |
| INVALID_MESSAGE_CONTAINER | message_container nu este un obiect. |
| INVALID_MESSAGE_CONTAINER_TYPE | Tipul cardului nu este embed_message sau system_message . |
| MISSING_MESSAGE_CONTAINER_DESCRIPTION | Un card are nevoie de o descriere, cu excepția cazului în care este un loader. |
| MISSING_MESSAGE_CONTAINER_LOADER_TEXT | Un card de tip loader are nevoie de loader_text . |
| INVALID_WEBHOOK_BINDING | Acest webhook nu are voie să posteze în acel canal. |
| INVALID_SIGNATURE | Antetul de semnătură lipsește sau este greșit. |
| REQUEST_BODY_TOO_LARGE | Cererea depășește limita de dimensiune. |
| PUBLISH_FAILED | Mesajul nu a putut fi livrat. |
| INVALID_ACTIONS_FORMAT , INVALID_ACTION_MISSING_FIELDS , DUPLICATE_ACTION_ID , INVALID_TRIGGERS_FORMAT , INVALID_TRIGGER_MISSING_ACTION , INVALID_TRIGGER_ACTION_NOT_ALLOWED | Ceva nu este în regulă cu un buton. Vezi [butoane](https://docs.mss.gs/ro/buttons). |

### Erori de fișiere

| Cod | Semnificație |
| --- | --- |
| INVALID_ATTACHMENTS_FORMAT | attachments nu este o listă sau o intrare nu este un obiect. |
| TOO_MANY_ATTACHMENTS | Mai mult de cinci fișiere. |
| MISSING_ATTACHMENT_NAME | Un fișier nu are nume. |
| INVALID_ATTACHMENT_NAME | Din nume nu rămâne nimic utilizabil, de exemplu .. . |
| MISSING_ATTACHMENT_SOURCE | Nici url , nici content_base64 . |
| AMBIGUOUS_ATTACHMENT_SOURCE | Atât url , cât și content_base64 . |
| INVALID_ATTACHMENT_BASE64 | Base64-ul nu poate fi decodat. |
| ATTACHMENT_TOO_LARGE | Un fișier are peste 8 MB după decodare. |
| INVALID_ATTACHMENT_URL | url nu este o adresă mssgs. |

## Limite

| Limită | Valoare |
| --- | --- |
| Dimensiunea cererii | Aproximativ 10 MB |
| Fișiere per mesaj | 5, de până la 8 MB fiecare |
| Descrierea cardului | Până la 50.000 de octeți. Peste 1.000 de octeți, membrii văd începutul și un buton **Show more**. |
| Actualizarea mesajului după postare | 30 de minute, prin callback_url |
| Fluxul live al unui mesaj cu butoane | 10 minute sau o oră, la cerere |

Cererile au o limită de frecvență. Când primești un 429 , așteaptă înainte să trimiți din nou și grupează alertele care vin în rafale într-un singur mesaj.

## GitHub, UniFi și App Store Connect

Îndreaptă unul dintre aceste servicii spre un URL de webhook, iar mssgs îl recunoaște și postează un card ca lumea, fără să scrii vreun payload. Vezi [integrări](https://mss.gs/ro/integrations). Acestea primesc ca răspuns {"success": true} și niciun URL de callback.

| Sursă | Recunoscut după | Ce postează |
| --- | --- | --- |
| GitHub | Antetul x-github-event | Push-uri, pull request-uri și review-uri, issue-uri și comentarii, branch-uri și taguri, release-uri. O rafală de modificări la același issue sau pull request este adunată într-un singur card. |
| UniFi Protect | User agent-ul protect-alarm-manager | Sonerii, mișcare, precum și persoane, vehicule sau colete detectate de camerele tale. |
| App Store Connect | Corpul notificărilor lui sau antetul x-apple-signature | Notificări App Store Connect. |

## Construiește mai departe