Incoming and outgoing webhooks
No bot needed. An incoming webhook is a URL that posts into one channel; an outgoing webhook sends one channel's events to your service as signed JSON.
Who manages them
Webhooks are an admin tool: only the Owner and members with Administrator create or manage them, under Webhooks in a channel's menu or through /api/admin. A webhook belongs to its channel, not to a person, and keeps working when its maker loses a role.
Incoming webhooks
Create one; the answer carries the URL, and its token is shown once:
POST /api/admin/channels/{channelId}/webhooks {"name": "CI"}
Post to it:
curl -X POST "$WEBHOOK_URL?wait=true" \
-H 'Content-Type: application/json' \
-d '{"content": "build **passed**", "username": "CI", "embeds": [{"title": "Run 42", "url": "https://ci.example/run/42", "color": 65280, "fields": [{"name": "tests", "value": "812", "inline": true}]}]}'
- The secret in the URL is the only credential. No cookie or Origin header is needed; the route is for servers and scripts, not browsers.
?wait=trueanswers200with the created message, otherwise204.?thread_id=<message id>posts into a thread.- JSON, or
multipart/form-datawith the JSON in apayload_jsonpart and up to 10 files. - A message is authored by the webhook with a Webhook badge, never by a member. Text is Markdown like any message.
The widely used execute format works as is:
| Field | In Mnema Talk |
|---|---|
content | up to 4000 characters |
username | 1 to 80 characters, unless the webhook's allow_identity_override is off |
avatar_url | ignored: the server never loads pictures from other hosts; set the avatar on the webhook |
embeds | title, description, url, color, timestamp, fields, footer.text, author.name/url, image.url, thumbnail.url; 10 embeds, 25 fields, 6000 characters in total; pictures are shown as links |
allowed_mentions | parse with users, everyone and roles, plus users and roles id lists; @username notifies by default, @all/@here only when asked for and allowed |
tts, flags, components, poll, thread_name | accepted and ignored |
Each webhook has its own settings: allow_everyone (off), allow_user_mentions, allow_attachments, allow_embeds and allow_identity_override (on). Whoever holds the URL gets exactly these, so treat it like a password; POST /api/admin/webhooks/{id}/token makes a new one and the old URL stops at once.
| Status | code | When |
|---|---|---|
| 400 | 50006 | nothing to post |
| 400 | 50035 | invalid body or field, too many files |
| 401 | 50027 | wrong token |
| 404 | 10015 / 10003 | unknown webhook / unknown thread_id |
| 413 | 40005 | body or file too large |
| 415 | 50035 | file type not allowed |
| 429 | rate limited, with retry_after and a Retry-After header |
Limits: about 5 requests per 2 seconds per webhook and 30 per minute per channel; JSON bodies up to 1 MiB; 15 webhooks per channel.
Outgoing webhooks
POST /api/admin/channels/{channelId}/outgoing-webhooks
{"name": "CI", "url": "https://ci.example.org/mnema", "events": ["MESSAGE_CREATE"]}
The answer carries the signing secret, shown once (whsec_…). Up to 10 per channel; each receives its own channel's events only.
| Event | When | d |
|---|---|---|
MESSAGE_CREATE | a message is posted (not ones from an incoming webhook) | the message |
MESSAGE_UPDATE | a message is edited | the message |
MESSAGE_DELETE | a message is deleted | {id, channel_id, parent_id} |
MESSAGE_REACTIONS_UPDATE | a reaction changes | {message_id, channel_id, reactions} |
VOICE_STATE_UPDATE | someone joins or leaves a Talk of the channel | {action, channel_id, user...} |
PING | the "send test event" button | {message} |
The request is a POST with JSON:
{
"id": "6f1c...",
"t": "MESSAGE_CREATE",
"timestamp": "2026-10-17T09:30:00Z",
"webhook_id": "b0a1...",
"channel_id": "93de...",
"d": { "id": "...", "content": "hello", "user_id": "...", "...": "..." }
}
Headers: X-Mnema-Event, X-Mnema-Delivery (the same as id), User-Agent: MnemaTalk-Webhook/<version> and X-Mnema-Signature: t=<unix seconds>,v1=<hex>. Answer with any 2xx within 10 seconds.
Verify the signature
v1 is the HMAC-SHA256 of "<t>.<raw body>" with your secret. Recompute over the raw body, compare in constant time, and refuse old t values. t is the time of this attempt, so the tolerance holds for retries too; do not apply it to timestamp in the body.
import { createHmac, timingSafeEqual } from 'node:crypto'
export function verify(secret, header, rawBody, toleranceSeconds = 300) {
const { t, v1 } = Object.fromEntries(header.split(',').map(p => p.split('=')))
if (Math.abs(Date.now() / 1000 - Number(t)) > toleranceSeconds) return false
const expected = createHmac('sha256', secret).update(`${t}.`).update(rawBody).digest('hex')
return expected.length === v1.length && timingSafeEqual(Buffer.from(expected), Buffer.from(v1))
}
import hmac, hashlib, time
def verify(secret: str, header: str, raw_body: bytes, tolerance=300) -> bool:
parts = dict(p.split("=", 1) for p in header.split(","))
t, v1 = parts["t"], parts["v1"]
if abs(time.time() - int(t)) > tolerance:
return False
expected = hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, v1)
Delivery
- Retries after 5 seconds, 30 seconds, 2, 10 and 30 minutes for network errors, timeouts,
5xx,408and429: up to 6 tries in about 45 minutes. Other4xxand redirects are not retried. - Five events in a row that failed for good switch the webhook off; switching it on starts over.
- Pending deliveries are kept in PostgreSQL in the same transaction as the change, so they survive a restart or update.
- At least once, best-effort order. Deduplicate on the delivery
id; sort bytimestampif order matters. - The last 50 attempts are in
GET /api/admin/outgoing-webhooks/{id}/deliveries, without the receiver's response body.
Where requests may go
The server only sends to public addresses: it resolves the name itself, refuses the whole host if any answer is private, loopback, link-local or a cloud metadata address, connects to exactly the address it checked, and never follows redirects. An operator can allow chosen internal targets with WEBHOOK_ALLOW_PRIVATE_TARGETS. Never any direct-message content, in either direction.
The full reference: doc/webhooks.md and the Webhooks section of the REST reference.