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=true answers 200 with the created message, otherwise 204. ?thread_id=<message id> posts into a thread.
  • JSON, or multipart/form-data with the JSON in a payload_json part 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:

FieldIn Mnema Talk
contentup to 4000 characters
username1 to 80 characters, unless the webhook's allow_identity_override is off
avatar_urlignored: the server never loads pictures from other hosts; set the avatar on the webhook
embedstitle, 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_mentionsparse 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_nameaccepted 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.

StatuscodeWhen
40050006nothing to post
40050035invalid body or field, too many files
40150027wrong token
40410015 / 10003unknown webhook / unknown thread_id
41340005body or file too large
41550035file type not allowed
429rate 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.

EventWhend
MESSAGE_CREATEa message is posted (not ones from an incoming webhook)the message
MESSAGE_UPDATEa message is editedthe message
MESSAGE_DELETEa message is deleted{id, channel_id, parent_id}
MESSAGE_REACTIONS_UPDATEa reaction changes{message_id, channel_id, reactions}
VOICE_STATE_UPDATEsomeone joins or leaves a Talk of the channel{action, channel_id, user...}
PINGthe "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, 408 and 429: up to 6 tries in about 45 minutes. Other 4xx and 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 by timestamp if 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.

Something wrong on this page? Tell us.