Slack and email

People should not have to keep a page open to find out a note was left. The notifier watches a board and sends a short summary to a Slack channel, to people by email, or both, with a link to each note.

Notefix · staging: 1 new, 1 decision
• New from Ben on /checkout: "The pay button is too faint on the dark theme" · Open
• Decision from Ana on /: "Keep the green header" · Open

What it tells people#

• A new note
• A note turned into a decision
• A note marked done, with its ticket number if it was filed
• A note reopened
• Someone agreeing to a decision

Edits, moving cards, archiving and deleting stay quiet. A note has to stay unchanged for 30 seconds before it counts, so a typo fixed straight after saving does not send a correction, and changes arriving close together are gathered into one message. With the default settings, a note reaches Slack about two minutes after it is saved.

The first time it runs, it sends nothing. It takes note of the board as it is, so starting it on a board with history never floods the channel.

Slack#

1Make a Slack webhook

1. Open api.slack.com/apps and press Create New App, then From scratch.
2. Name it Notefix, pick your workspace, and press Create App.
3. In the menu on the left, open Incoming Webhooks and switch it on.
4. Press Add New Webhook, choose the channel, and press Allow.
5. Copy the Webhook URL. It starts with https://hooks.slack.com/services/.

2Write the settings file

On the server where the store runs:

sudo mkdir -p /etc/notefix /var/lib/notefix
sudo install -m 600 -o "$USER" /dev/null /etc/notefix/notify.env
nano /etc/notefix/notify.env

NOTEFIX_API=http://127.0.0.1:8097
NOTEFIX_BOARD=staging
NOTEFIX_SITE=https://staging.acme.com
NOTIFY_SLACK_WEBHOOK=https://hooks.slack.com/services/paste-yours
NOTIFY_STATE=/var/lib/notefix/notify-staging.json
NOTIFY_SLACK_CHANNEL=#design-review
NOTEFIX_SECRET=the-secret-you-gave-the-store

• NOTIFY_STATE is where it remembers what it has already announced.
• NOTIFY_SLACK_CHANNEL is only a label: the channel's name as Settings should show it. Slack does not tell programs which channel a webhook posts to.
• NOTEFIX_SECRET lets it tell the store it is running, so Settings → Connected tools shows Slack as working.

3Try it

See what it would send, without sending anything:

set -a; . /etc/notefix/notify.env; set +a
NOTEFIX_DRY_RUN=1 python3 connectors/notify.py

Leave a note on your page and wait about two minutes: the message is printed instead of posted. When it looks right, run it without NOTEFIX_DRY_RUN, then as a service:

# /etc/systemd/system/notefix-notify.service
[Unit]
Description=Notefix notifier
After=network.target

[Service]
User=notefix
EnvironmentFile=/etc/notefix/notify.env
ExecStart=/usr/bin/python3 /opt/notefix/connectors/notify.py
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

When a connection breaks#

If a tracker, Slack or email stops working, for example because its key expired, the notifier tells your team once, and again once it works:

⚠️ Notefix · staging: Jira has stopped working. The key it uses has stopped working, most likely expired or revoked. Notes sent to Jira wait on the board until it is fixed.
✅ Notefix · staging: Jira is working again.

• It goes to the Slack channel, and to NOTIFY_ALERT_EMAIL if you set one: an address for whoever runs the server. Never to people who signed up for news about their notes.
• If Slack is what broke, only the email is sent.
• A problem has to last two minutes before anyone is told, so a service that hiccups once says nothing. The same problem is never announced twice.
• A connector stopped on purpose is not a problem, and says nothing.

On the page, a broken connection also shows as an amber dot on the Settings gear and a line at the top of All notes, which opens Connected tools.

Email#

Email goes out through the mail service you already use (Postmark, Amazon SES, Resend, Google Workspace or your own server) and comes from your own domain. There is no Notefix mail service in between.

It reaches two kinds of people:

• People who sign up from the page. With email set up, Settings gains a Notifications section. A reviewer enters their address, confirms it from one email, and from then on hears about changes to their own notes, such as one marked done or reopened.
• People you list yourself, like a client's project lead, in a file you keep.

Every email has a link to change how often, or stop, and mail apps get a one-click Unsubscribe.

1Add email to the settings file

Add these to /etc/notefix/notify.env:

NOTIFY_EMAIL_FROM="Notefix <[email protected]>"
NOTIFY_SMTP_HOST=smtp.postmarkapp.com
NOTIFY_SMTP_USER=your-smtp-user
NOTIFY_SMTP_PASSWORD=your-smtp-password
NOTEFIX_SECRET=the-secret-you-gave-the-store
NOTEFIX_PUBLIC_API=https://staging.acme.com/notefix-api

Email is refused without the secret and the public address, because an email with no way to stop it is not one Notefix will send.

2Optional: people who did not sign up

Make a file, for example /etc/notefix/people.json:

[
  { "email": "[email protected]", "names": ["Ana"], "every": "batch", "about": "all" },
  { "email": "[email protected]", "names": ["Sam"], "every": "daily", "about": "mine" }
]

And add NOTIFY_EMAIL_PEOPLE=/etc/notefix/people.json to the settings file. What someone chooses from the link in an email always wins over this file.

Test email without sending it#

Run Mailpit on your computer, and point the notifier at it with NOTIFY_SMTP_HOST=127.0.0.1 NOTIFY_SMTP_PORT=1025 NOTIFY_SMTP_TLS=none. Every email appears in Mailpit's window instead of anyone's inbox.

All the notifier's settings are in the Reference.