Home › Settings Reference

Settings Reference

Six editable provider settings apply to every rule, plus a read-only version row. Six rule settings can differ per notification.

Provider settings are configured once under Configuration → System Settings → Notifications → Configure (Stoat). Rule settings appear when a notification rule selects Stoat as its provider.

Provider settings

Field	Key	Default	Notes
Webhook URL	`webhook`	none	Required. Must be HTTPS and look like `https://stoat.chat/api/webhooks/{id}/{token}`.
Version	`version`	`1.0.0`	Read-only row shown in the configuration dialog. It is not saved and cannot be edited.
Sender Name	`displayName`	empty	Optional masquerade name, maximum 32 characters. The placeholder suggests `WHMCS`. Blank posts as the webhook’s own name.
Sender Avatar URL	`avatarUrl`	empty	Optional HTTPS image URL, maximum 256 characters.
Allow Self-Hosted Host	`allowSelfHosted`	No	Permits a host other than `stoat.chat` / `*.stoat.chat`. HTTPS is still required.
Request Timeout	`timeout`	`10`	Seconds, 1–30. Invalid values fall back to 10. Connection timeout is capped at 5 seconds.
Strict Delivery	`strictMode`	No	When ticked, a rejected embed or masquerade fails the notification instead of retrying without it.

Rule settings

Field	Key	Default	Notes
Webhook Override	`webhook`	empty	Send this rule to a different channel. Same validation as the provider webhook.
Message Format	`format`	`both`	`both` (Message + Embed), `markdown` or `embed`.
Embed Colour	`colour`	empty	CSS colour applied to the embed accent. Empty uses Stoat’s default.
Include Attributes	`showAttributes`	Yes	Adds notification attributes such as client, invoice, service or department.
Attributes Inline	`inline`	No	One line separated by dots instead of one attribute per line.
Silent Message	`silent`	No	Sends with Stoat’s suppress-notifications flag so the channel does not ping.

Message format choices

Value	What is sent	Permissions
`both`	Short linked title in the message body plus a full embed.	SendMessages, SendEmbeds
`markdown`	A single Markdown message with title, body, attributes and a view link.	SendMessages
`embed`	Everything inside the embed; the message body is empty.	SendMessages, SendEmbeds

Strict delivery and fallback

With Strict Delivery off (the default), the module retries once when Stoat rejects an optional feature for a missing permission:

SendEmbeds missing in Message + Embed mode → the embed is removed and the Markdown message is delivered.
Masquerade missing → the masquerade is removed and the message is posted as the webhook’s own identity.

Both attempts appear in the module log, the second marked execute webhook (retry). In Embed only mode there is no fallback, because the message body would be empty; the notification fails with a clear error instead.

With Strict Delivery on, nothing is removed. Use it when the appearance must be guaranteed and a failed notification is preferable to a degraded one.

Examples

One channel for everything

Provider webhook: the #whmcs channel webhook.
Every rule leaves Webhook Override blank.
Format Message + Embed, attributes on.

Billing and support in separate channels

Provider webhook: #whmcs.
Invoice and order rules: override with the #billing webhook, colour #2ecc71.
Ticket rules: override with the #support webhook, colour #e67e22.
Service and domain rules: no override, colour #5865f2.

Quiet audit channel

Format Message only.
Silent Message ticked.
Include Attributes ticked, Attributes Inline ticked to keep it compact.

Validation rules

Value	Validation
Webhook URL	HTTPS only; no credentials, query string or fragment; path must end in `/api/webhooks/{id}/{token}`; host limited to `stoat.chat` / `*.stoat.chat` unless self-hosted is allowed; port 443 unless self-hosted.
Sender name	Whitespace collapsed, truncated to Stoat’s 32-character limit.
Sender avatar	Must be a valid HTTPS URL of 256 characters or fewer.
Timeout	Integer 1–30; anything else becomes 10.
Embed colour	Stoat’s CSS colour grammar: named colours, `#hex`, `rgb()`, `rgba()`, `var(--token)` and gradients. Decimal integers are converted to hex. Maximum 128 characters.
Format	Only `both`, `markdown` or `embed`; anything else uses `both`.

Decimal colours still work — if you are migrating a rule that used a Guilded-style decimal colour such as 5793266, it is converted to #5865f2 automatically.