Minctrl Docs
Guides

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

EventWhoMessage
A gate parkseveryone who may sign it"Waiting for your signature"
An SLA level is reachedthe roles the step's SLA names (notify_roles), else the signers"Still waiting — SLA level N"
A deadline is missedthe 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 statusMeans
sentdelivered (replaced_at: the Slack message has since been replaced by the outcome)
pending with deferred_reasonwaiting for the recipient's quiet hours to end
pending with attempts > 0a temporary failure (rate limit, 5xx, network) — retried with backoff, at most 5 times
failedgiven up, with the reason — e.g. Slack: users_not_found (no Slack user has this email)
skippednot 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.

  1. In Minctrl, Settings → Notifications → Show the app manifest. It carries your company's interaction URL.
  2. At api.slack.com/apps choose Create New App → From a manifest, pick your workspace, paste the manifest, create and Install to Workspace.
  3. 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).
  4. 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
  }
}
ScopeWhy
chat:writesend the direct message and replace it with the outcome
users:read, users:read.emailfind 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:

  1. Minctrl verifies the request: X-Slack-Signature over 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 with 403 until Slack is set up again), and each request accepted once (a replay answers 409).
  2. 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.
  3. 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.
  4. 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.
  5. The gate_signed audit 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

MethodPathWho
GET/notifications/settingsany member
PUT/notifications/settingsowner, admin
PUT / DELETE/notifications/settings/slackowner, admin
POST/notifications/settings/slack/testowner, admin
GET/notifications/settings/slack/manifestany member
POST/notifications/settings/teams, DELETE /notifications/settings/teams/{id}owner, admin
GET / PUT/notifications/preferencesthe caller
GET/notifications/runs/{run_id}any member; an API key with runs:read
POST/integrations/slack/{company_id}/interactionsSlack only (signed)

Server settings

VariableDefaultEffect
NOTIFY_POLL_SECONDS5how often the dispatcher runs; 0 turns it off
MINCTRL_SECRETS_KEYderived from JWT_SECRETkey the Slack and Teams secrets are sealed with
RESEND_API_KEY—email provider; without it email deliveries are skipped
APP_URLhttps://app.minctrl.comthe links in messages and the Slack interaction URL

On this page