Notifications, Slack and Teams
Tell the people who may sign a gate that it waits — by email, Slack or Microsoft Teams — and let them sign a plain gate from the Slack message, through the same checks as the console.
When a run parks at a gate, Minctrl tells the people who may sign it: members whose role
holds gate.approve (manager, admin, owner), minus whoever separation of duties keeps off the
gate — the person who started the run, and anyone who already signed another gate of it. Each
person is told on their channels; a Teams channel gets a link for everyone. SLA
escalations and missed deadlines go out the same way.
Slack signs only what is safe to sign in one click. A gate is signable from Slack when it has no form, one signature clears it, and none of its outcomes authorizes a live irreversible action. Anything else — or anything Minctrl cannot tell, such as connectors it could not read — gets one Open in Minctrl button that lands on the sign-off card for that run.
Who is told, and when
| Event | Who | Message |
|---|---|---|
| A gate parks | everyone who may sign it | "Waiting for your signature" |
| An SLA level is reached | the roles the step's SLA names (notify_roles), else the signers | "Still waiting — SLA level N" |
| A deadline is missed | the same | "Missed its deadline — still waiting" |
The notice is queued in the same transaction that records the park (or the SLA entry) and
sent after the commit by a background dispatcher, so telling people never slows or fails
the run. If queuing itself fails, the run goes on and its park is marked notify_failed.
Email arrives as one digest per person per pass, so a backlog after an outage is one email, not a storm. A Slack message goes out per gate. A gate signed before its notice went out is not sent at all.
Where it is recorded
Every notice and every message has a record you can see on the run (Runs → a run →
Notifications) and read with GET /notifications/runs/{run_id}:
| Delivery status | Means |
|---|---|
sent | delivered (replaced_at: the Slack message has since been replaced by the outcome) |
pending with deferred_reason | waiting for the recipient's quiet hours to end |
pending with attempts > 0 | a temporary failure (rate limit, 5xx, network) — retried with backoff, at most 5 times |
failed | given up, with the reason — e.g. Slack: users_not_found (no Slack user has this email) |
skipped | not sent, with the reason — e.g. email is not configured on this server |
A recipient list that could not be read is not "nobody to notify": the notice stays
pending with the error and is retried, then recorded as failed. A notice nobody could
receive (no other signer, everyone opted out, no Teams channel) is no_recipients. Any failed,
skipped or unreceived notice also sets the park's notify_failed flag, which the sign-off card
shows.
Your own preferences
Settings → Notifications → Your notifications. For email and Slack choose Company default, On or Off; for quiet hours choose the company's, none, or your own window (it may cross midnight, e.g. 22:00–07:00 Europe/Berlin). A notice that falls in quiet hours waits and goes out when they end. The panel says what applies to you right now.
curl -s -X PUT "$API/notifications/preferences" -H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"email": null, "slack": true, "quiet_mode": "custom",
"quiet": {"start": "22:00", "end": "07:00", "timezone": "Europe/Berlin"}}'Company channels (owner or admin)
Settings → Notifications → Company channels: email and Slack defaults for members who chose
nothing, default quiet hours, the Slack app and the Teams channels. Every change is written to
the audit chain as notifications_changed — what changed, by whom — in the same transaction.
The Slack bot token, the signing secret and a Teams webhook URL are stored encrypted
(AES-256-GCM under MINCTRL_SECRETS_KEY) and are never shown or returned again.
Set up Slack
Each company installs its own Slack app, so messages come from your workspace and Minctrl holds a token for nothing else.
- In Minctrl, Settings → Notifications → Show the app manifest. It carries your company's interaction URL.
- At api.slack.com/apps choose Create New App → From a manifest, pick your workspace, paste the manifest, create and Install to Workspace.
- Copy OAuth & Permissions → Bot User OAuth Token (
xoxb-…) and Basic Information → Signing Secret into Minctrl and choose Connect Slack. Minctrl checks the token with Slack (auth.test) before storing anything and remembers the workspace (a token whose workspace Slack does not name is refused). - Send me a test message proves that the token works and that Slack has a user with your email.
The manifest Minctrl shows looks like this (with your company's id in the URL):
{
"display_information": {
"name": "Minctrl",
"description": "Gates waiting for your signature, signed where you work.",
"background_color": "#1f2a24"
},
"features": {
"bot_user": { "display_name": "Minctrl", "always_online": true },
"app_home": { "messages_tab_enabled": true, "messages_tab_read_only_enabled": true }
},
"oauth_config": { "scopes": { "bot": ["chat:write", "users:read", "users:read.email"] } },
"settings": {
"interactivity": {
"is_enabled": true,
"request_url": "https://app.minctrl.com/api/integrations/slack/<company-id>/interactions"
},
"org_deploy_enabled": false,
"socket_mode_enabled": false,
"token_rotation_enabled": false
}
}| Scope | Why |
|---|---|
chat:write | send the direct message and replace it with the outcome |
users:read, users:read.email | find the Slack user with a member's email, and read the confirmed email of whoever presses a button |
Minctrl finds each person on Slack by their email (users.lookupByEmail). A member whose
Minctrl email is not a Slack user's email gets no Slack message — the delivery says
users_not_found.
Signing from Slack
A signable gate's message shows its outcomes as buttons (Approve, Deny…, or the branch names of a multi-outcome gate) and Open in Minctrl. When someone presses one:
- Minctrl verifies the request:
X-Slack-Signatureover the raw body with your signing secret, a timestamp no older than 5 minutes, the workspace you connected (a company whose workspace is not known refuses every press with403until Slack is set up again), and each request accepted once (a replay answers409). - It asks Slack for the presser's confirmed email and maps it to an active member of the company. No such member — nothing is signed.
- It checks again that the gate is still signable from Slack (a connector may have gone live since the message was sent) and that the button is for the pass the run waits at now.
- It signs through the same door as the console (
POST /process-runs/{id}/resume): the presser's role must allow it, separation of duties applies, a refusal needs its reason. A Deny opens a dialog that asks for the reason first. - The
gate_signedaudit entry records"channel": "slack"and the signer's email and role. The message is replaced by the outcome ("Approved by … (manager) from Slack").
Anything refused — unknown person, a role that may not sign, a separation-of-duties conflict, a stale button — is answered only to the person who pressed it, and nothing is signed. When a gate is signed anywhere else (the console, another person's Slack), the other Slack messages for it are replaced with who signed it.
A gate that is not signable from Slack says why under its Open in Minctrl button: it has a form to fill in, it needs more than one signature, or it authorizes a live irreversible action that needs its gate id typed.
Microsoft Teams
Add a channel's incoming webhook (or a Teams Workflows "When a Teams webhook request is
received" URL) under Microsoft Teams → Add channel. Every notice posts an Adaptive Card with
what waits, the deadline and Open in Minctrl. Teams cannot sign. The URL must be a public
https:// address; only its host is shown afterwards.
API
| Method | Path | Who |
|---|---|---|
GET | /notifications/settings | any member |
PUT | /notifications/settings | owner, admin |
PUT / DELETE | /notifications/settings/slack | owner, admin |
POST | /notifications/settings/slack/test | owner, admin |
GET | /notifications/settings/slack/manifest | any member |
POST | /notifications/settings/teams, DELETE /notifications/settings/teams/{id} | owner, admin |
GET / PUT | /notifications/preferences | the caller |
GET | /notifications/runs/{run_id} | any member; an API key with runs:read |
POST | /integrations/slack/{company_id}/interactions | Slack only (signed) |
Server settings
| Variable | Default | Effect |
|---|---|---|
NOTIFY_POLL_SECONDS | 5 | how often the dispatcher runs; 0 turns it off |
MINCTRL_SECRETS_KEY | derived from JWT_SECRET | key the Slack and Teams secrets are sealed with |
RESEND_API_KEY | — | email provider; without it email deliveries are skipped |
APP_URL | https://app.minctrl.com | the links in messages and the Slack interaction URL |
Escalation, delegation and N-of-M approvals
Require several signatures on a gate, hand your gates to a delegate while you are away, assign a waiting gate to a named member, and let a deadline's escalation level reassign it — without anything ever signing or rerouting a run on its own.
Approvals in Teams and on your phone
Sign a plain gate from a Microsoft Teams card through your company's own bot, get a Web Push on your phone when a gate waits, and sign on a phone-first screen — through the same checks as the console.