Settings and controls

Settings and controls

Settings drive the Admin / project / member forms. Keys use ^[a-z][a-z0-9_-]{0,32}$ and must be unique within the extension.

Setting object

Field	Required	Notes
key	yes	Unique within the extension.
type	yes	See types below.
label	yes	Form label.
description	no	Help text under the field. Max 400 characters.
required	no	UI hint. An empty secret still skips delivery rather than erroring.
scope	no	site (default), project, or member.
options	select only	{ "value", "label?" } list.

Site admin persists enabled plus site-scoped secrets, site triggers/templates, test, and delivery retry. Webhook URL, triggers, templates, and filters for project notifications live on the project. Use "scope": "project" for those. "scope": "member" settings appear on Settings → Integrations (“Notify me”).

An extension appears on the project Extensions tab if it has any project-scoped setting, any member-scoped setting, any custom fields, or a ui panel.

Generic select / status / user / string / int values are sent on JSON webhooks as config (and {config_json}).

Types

Type	Purpose
secret	Encrypted value (webhook URL, ntfy token). The API never returns the secret, only whether it is set.
hook_select	Trigger checkboxes, one per declared hook. Conventional key: triggers. May include *.
bool	Boolean flag.
string	Free-text value stored in config.
int	Integer value stored in config.
select	Dropdown; requires options. Stored in config.
status	Project status picker. Stored in config.
user	Project member picker. Stored in config.
priority	Minimum task priority filter. Key must be min_priority.
tag_ids	If any tags are selected, only matching tasks notify. Key must be tag_ids.
status_ids	If any statuses are selected, only matching tasks notify. Key must be status_ids.
status_exclude_ids	Skip tasks in these statuses. Key must be status_exclude_ids.
time	Clock time. Used as a pair: quiet_hours_start and quiet_hours_end. Leave start blank to send immediately.
digest	Batch notifications hourly or daily instead of sending immediately. Key must be digest.
field_filter	Only notify when this custom field key matches (and equals the value if set). Key must be field_filter.
mention_map	JSON map of Ordryn usernames to chat mentions. Key must be mention_map. Replaces {actor} when the username matches.
project_ids	Accepted in the manifest; no host UI in API 1. Do not rely on it.

Conventional keys

These keys are not special types; the host recognizes the combination of key + type used by the notification examples. Filters only apply if the key is declared in the manifest.

Key	Type	Effect
webhook_url	secret	Target URL. Must match delivery.url_from.
ntfy_auth	secret	Optional Bearer token for ntfy.webhook.
triggers	hook_select	Which declared hooks the destination opted into.
status_only	bool	Skip task.updated unless kanban/list status changed.
skip_self	bool	Do not post when you are the actor.
claimed_only	bool	Skip events for tasks that nobody has claimed.
claimed_is_me	bool	Member-scoped: only events for cards you have claimed.
min_priority	priority	Ignore events below this priority.
tag_ids	tag_ids	Restrict to selected tags.
status_ids	status_ids	Restrict to selected statuses.
status_exclude_ids	status_exclude_ids	Skip selected statuses.
quiet_hours_start / quiet_hours_end	time	Hold deliveries until the window ends (project timezone).
digest	digest	Hourly or daily batching. Digest bodies list up to 10 {name} ({event}) lines.
field_filter	field_filter	Match a custom field key (and optional value).
mention_map	mention_map	Username → chat mention JSON.

Discord’s example omits quiet-hour settings; most other notification examples include the full filter set. claimed and mentions use scope: member for “Notify me”. callback-bot demos select / status / user.

Controls

controls is an array of panel actions.

Control	What it does
send_test	Send a test POST. Bypasses enable/trigger filters; still needs a webhook URL.
rotate_signing	Rotate the HMAC signing secret shown once on the panel. Requests then include X-Ordryn-Signature: sha256=<hex> over the raw JSON body.
sample_json	Show a sample JSON body for the delivery.
rotate_callback	Rotate the project-scoped callback token (odycb_…). Shown once. See Callbacks and inbound.

join-requests declares only send_test. discord declares send_test and sample_json (no rotate_signing). callback-bot declares all four. The generic webhook, Slack, Teams, Google Chat, ntfy, email, and similar examples declare send_test, rotate_signing, and sample_json.

Site vs project vs member

Pattern	Behavior
Default notification examples	Site: enable only. Secrets, triggers, templates, filters: scope: "project".
Join requests	webhook_url with scope: "site"; join.request / join.approved / join.denied; no project Extensions tab.
Member “Notify me”	Settings with scope: "member" (for example claimed_is_me, member skip_self). Blocked on kanban project tasks.
Field extensions	Project enablement; they appear on the project tab because they have fields.
Panel / callback	Appear on the project tab because of ui and/or project settings.

Personal inbox tasks (no project) do not get custom fields. Failed deliveries become dead after 8 attempts; owners can retry from Admin, the project Extensions tab, or Settings → Integrations.