Chat webhooks and rich messages
Chat webhooks connect a group chat to your other tools. An incoming webhook is a secret address that CI, monitoring, n8n, Zapier or a script posts to: the message appears in the chat as a bot, as plain text or as a rich message (a message card with a title, colour, formatted text, fields, images, files and buttons). An outgoing webhook sends every new message of the chat to an address of yours, signed, so an automation can react to it.
Incoming webhooks also post in groups where Only admins post (the chat's owner and admins and the company administrators). That makes a read-only "Alerts" or "Releases" group easy to build.
Who can set them up
The owner of the group and company administrators (users with settings:write for the whole company). Open the chat in the console, press Chat settings and go to Webhooks. A group has at most 10 webhooks. Every change is in the audit log.
In the same dialog the owner chooses Who can post (Everyone, or Only admins: members read and react; the API calls it announcement) and makes members Admin (they post when only admins post, pin messages as the chat's banner and delete any message).
Incoming webhooks
- In Chat settings → Webhooks, choose Incoming, give it a name (for example
CI), optionally a bot name and a rate limit (messages a minute, 1 to 600, default 30), and press Create webhook. - Copy the address. It is shown only once: the server keeps only a hash of it. Anyone who has the address can post into the chat, so treat it like a password.
- Post JSON to it. No sign-in is needed: the address is the credential.
The list shows each webhook's first characters, its limit and when it was last used. New address (rotate) replaces the address at once (the old one stops working), Turn off pauses it, and Revoke deletes it. A rotated, paused, revoked or unknown address answers 404.
Plain text
curl -X POST "https://pbx.example.com/api/v1/public/chat/hooks/<token>" \
-H 'Content-Type: application/json' \
-d '{"text": "Nightly backup **finished** in 4 min."}'
The answer is {"ok": true, "message_id": "...", "seq": 13}.
A rich message (message card)
curl -X POST "https://pbx.example.com/api/v1/public/chat/hooks/<token>" \
-H 'Content-Type: application/json' \
-d '{
"title": "Deploy finished",
"title_url": "https://ci.example.com/runs/42",
"color": "good",
"text": "All checks **passed**. See the [log](https://ci.example.com/runs/42/log).",
"fields": [
{"label": "Environment", "value": "prod", "inline": true},
{"label": "Duration", "value": "12 min", "inline": true},
{"label": "Changes", "value": "- faster sign-in\n- new reports"}
],
"images": [{"url": "https://grafana.example.com/render/cpu.png", "alt": "CPU graph"}],
"files": [{"url": "https://ci.example.com/runs/42/report.pdf", "name": "report.pdf"}],
"buttons": [
{"label": "Open run", "url": "https://ci.example.com/runs/42", "style": "primary"},
{"label": "Roll back", "url": "https://ci.example.com/runs/42/rollback", "style": "danger"}
],
"footer": {"text": "CI", "timestamp": "2026-11-13T10:00:00Z"},
"sender_name": "Release bot"
}'
The same card may be sent under a card key. Every part is optional, but the card must show something.
| Part | Rules |
|---|---|
title, title_url | Plain text, at most 250 characters; the title links to title_url (https, http or mailto). |
color | #rrggbb, #rgb, good, warning, danger or info: the accent bar on the left. |
text, field value | The markdown subset below, at most 4000 characters (a field value 1000). |
fields | At most 25 label/value pairs. inline: true fields sit side by side; the others take the full width. |
images | At most 4, by https URL: PNG, JPEG, GIF or WebP, at most 5 MiB each. |
files | At most 4, by https URL, within the chat attachment limit and the allowed file types. |
buttons | At most 5. Each opens its URL in the browser; style is default, primary or danger. |
footer | A short text and a time (RFC 3339 or Unix seconds), shown in the reader's time zone. |
sender_name, avatar_url | The bot's name for this message (default: the webhook's bot name). |
Markdown subset: **bold**, *italic* or _italic_, `code`, fenced code blocks (```), [label](https://...) links, - and 1. lists, and > quotes. HTML is removed, a link that is not https, http or mailto keeps only its label, and card numbers are masked.
Images and files are fetched once by MonoPbx when the message is posted, from public addresses only (the same guard as outbound webhooks: no private, loopback or internal addresses), size- and type-checked and scanned, then stored with the message. Readers never load anything from your server. If one cannot be fetched, the call fails with MPBX-CHAT-CARD-FETCH-FAILED and nothing is posted.
Old clients and notifications show the card's plain-text version (title, text, fields and links as text).
Slack payloads
Payloads written for Slack incoming webhooks work as they are: text (mrkdwn), username, icon_url, legacy attachments (color, pretext, title, title_link, text, fields, image_url, footer, ts, URL actions) and the header, section, image, context, divider and actions blocks. Buttons without a URL are dropped.
curl -X POST "https://pbx.example.com/api/v1/public/chat/hooks/<token>" \
-H 'Content-Type: application/json' \
-d '{"username": "Grafana", "attachments": [{"color": "danger", "title": "CPU above 90%",
"title_link": "https://grafana.example.com/d/cpu", "fields": [{"title": "Host", "value": "pbx-1", "short": true}]}]}'
Limits and errors
| Answer | Meaning |
|---|---|
200 | Posted. |
400 MPBX-CHAT-CARD-INVALID | A part of the card is wrong; the detail names the JSON path, for example /buttons/0/url. |
400 MPBX-CHAT-CARD-VERSION | version is not 1. |
400 MPBX-CHAT-CARD-FETCH-FAILED | An image or file could not be fetched (private address, not https, too large, wrong type, no answer). |
404 | Unknown, rotated, paused or revoked address. |
413 | The body is larger than 64 KiB. |
429 MPBX-CHAT-WEBHOOK-RATE-LIMITED | More messages in a minute than the webhook's limit; wait for Retry-After. |
Outgoing webhooks
- In Chat settings → Webhooks, choose Outgoing, give it a name and the receiver's public
httpsURL, and press Create webhook. - Copy the signing secret (
whsec_...). It is shown only once. New secret replaces it.
Every new message of the chat (except those of its incoming webhooks, so automations cannot loop) is posted to the receiver:
{
"type": "chat.message.created",
"version": 1,
"room": {"id": "0199b5a2-6c1e-7d3a-9f00-3c8e1b2a5001", "name": "Releases"},
"message": {
"id": "0199b5a2-6c1e-7d3a-9f00-3c8e1b2a7002", "seq": 14,
"sender_user_id": "0199b5a2-6c1e-7d3a-9f00-3c8e1b2a4c01", "sender_name": "Ada Lovelace",
"body": "Looks good", "card": null, "parent_id": null, "attachment": null,
"created_at": "2026-11-13T10:02:00Z"
}
}
The request carries Standard Webhooks headers: webhook-id, webhook-timestamp and webhook-signature: v1,<base64 HMAC-SHA256> over <webhook-id>.<webhook-timestamp>.<body> with the secret (without its whsec_ prefix, base64-decoded). Check the signature and reject timestamps older than five minutes. A quick check in a shell:
secret_b64=${SECRET#whsec_}
printf '%s.%s.%s' "$WEBHOOK_ID" "$WEBHOOK_TIMESTAMP" "$BODY" \
| openssl dgst -sha256 -mac HMAC -macopt hexkey:$(printf '%s' "$secret_b64" | base64 -d | xxd -p -c 256) -binary \
| base64
Answer with any 2xx within 10 seconds. Other answers and timeouts are retried with backoff (from 30 seconds, doubling, up to 6 hours, 8 attempts). The webhook list shows the last delivery time and status (Delivered, Retrying or Failed) and the reason of the last failure (for example http_500, timeout, blocked). The address is checked against private and internal networks when it is saved and again on every attempt.
API
The console uses the same API (all under /api/v1, signed in):
| Method and path | What it does |
|---|---|
GET /chat/rooms/{id}/settings | Type, pin and size of a group. |
PUT /chat/rooms/{id}/type | {"room_type": "announcement"} or "discussion". |
PUT /chat/rooms/{id}/members/{user_id}/role | {"role": "admin"} or "member". |
PUT / DELETE /chat/rooms/{id}/pin | Pin a message ({"message_id": "..."}) as the banner, or clear it. |
GET / POST /chat/rooms/{id}/webhooks | List, or create (direction, name, bot_name, rate_per_min, url); the address or secret is in the create answer only. |
PATCH /chat/rooms/{id}/webhooks/{webhook_id} | Rename, turn on or off, bot name, rate, receiver URL. |
POST /chat/rooms/{id}/webhooks/{webhook_id}/rotate | New address or secret (shown once). |
DELETE /chat/rooms/{id}/webhooks/{webhook_id} | Revoke. |
POST /chat/rooms/{id}/messages | People and API keys send a card with "card": {...} (same schema). |
The full schema (ChatCard, ChatCardInput, ChatHookPayload) with examples is in the API reference.