Slack Alerts¶
Badger posts operational alerts to its own Slack workspace: failed Gift Aid claims, billing and plan notices, Stripe events, fulfilment problems and so on. Every environment (production, the demo cluster and a developer's machine) posts to the same channels through the same Slack app, so each message says which environment sent it.
How a message shows its environment¶
SlackEnvironment (in common, package alerts) reads the BDGR_ENVIRONMENT_NAME environment
variable and names the environment once, on the bot, on every message to Badger's workspace:
BDGR_ENVIRONMENT_NAME |
Bot name | Icon | Grey footer |
|---|---|---|---|
K3S-PRODUCTION |
badgerbot |
:badger: |
the pod |
K3S-DEVELOPMENT (the demo cluster) |
badgerbot · demo |
:test_tube: |
the pod |
| not set (a developer's machine) | badgerbot · local |
:computer: |
the machine, e.g. darth-zannah |
- The bot's name and icon say which environment. Slack shows the name on the message and in its
notification, so nothing is added to the text. Production keeps the plain name. A sender's own
bot name (
Badger billing,StripeAccountBot) is kept and gets the same suffix. - The grey footer under every message says which node sent it.
A developer's machine is named from BDGR_MACHINE_NAME, which devEnv.sh sets to the Mac's local
host name and passes into the app containers (set it in ~/devEnv.conf to choose another name).
Without it the footer shows the container's host name.
Any other value of the variable is shown in lower case without a leading k3s-, and counts as
production only if it then starts with prod.
Setting the bot's name and icon per message needs the Slack app's chat:write.customize scope.
The alert layout¶
New alerts are an AdminAlert (in common, package alerts), sent with
NotificationService.sendAdminAlert(alert, channel). The sender says what happened; the layout is
the same for every alert:
🔴 Gift Aid claim failed · Hedgerow Trust (hedgerow)
Nothing more is posted for this shop until HMRC has accepted its failed claims.
Tax period Reclaim
2025/26 £557.38
Next step: Correct the shop's HMRC Gateway username and password (Settings › Gift Aid), then Retry
submission 6741c0e2 · badger-worker-7d9f
notificationService.sendAdminAlert(
AdminAlert.failing("Gift Aid claim failed")
.shop(siteContext)
.summary("Nothing more is posted for this shop until HMRC has accepted its failed claims.")
.fact("Tax period", submission.getTaxPeriod())
.nextStep("Correct the shop's HMRC Gateway username and password (Settings › Gift Aid), then Retry")
.reference("submission " + submission.getId()),
"#badger-notifications");
| Part | Method | Notes |
|---|---|---|
| Headline | failing / attention / toDo / info / fixed, then shop(siteContext) |
The severity only changes the icon. The shop shows as "Name (id)" |
| Summary | summary(...) |
One or two plain sentences on the cause or effect |
| Facts | fact(label, value) |
Two-column grid. A blank value is left out |
| Next step | nextStep(...) |
What to do and on which screen. Leave out when there is nothing to do |
| Footer | reference(...) |
An id to find the record or log lines with, shown before the node that sent it |
| Severity | Icon | Use for |
|---|---|---|
failing |
🔴 | Broken, and stays broken until somebody acts |
attention |
⚠️ | Went wrong once and needs a look |
toDo |
🔧 | Nothing is wrong, but Badger staff have a job to do |
info |
ℹ️ | For the record |
fixed |
✅ | Something that was failing has recovered |
An alert carries ids, never personal data: name the order, donation or submission, not the customer. Values are escaped for Slack, so a cause copied from a provider's error can't break the layout.
Every alert Badger sends itself uses this layout, including a few that have only a headline
("Stripe connected · far-field"). shop(siteId) takes the id alone where the sender has no
SiteContext. sendAdminAlert(alert) with no channel posts to #badger-notifications.
Two kinds of message keep their own layout: the Stripe threads (below), and the application fee
notice built by SlackBlockKitBuilder and sent with sendAdminMessageWithJson. The plain
sendAdminMessage methods remain on NotificationService but nothing calls them: use an
AdminAlert for anything new.
The two ways a message is posted¶
- Through the notification queue.
NotificationService.sendAdminAlert(...),sendAdminMessage(...)andsendAdminMessageWithJson(...)(SlackNotificationService) put aSlackRequeston the queue and the worker'sSlackNotificationServiceListenerposts it. The service marks the environment; the listener adds the footer as a context block, under the sender's blocks or under the text. A text over 3,000 characters (Slack's limit for one block) is posted as plain text, without the footer. - Directly, for Stripe threads.
StripeSlackClientposts and edits the Stripe thread messages itself, because it needs the timestamp Slack returns. It marks the bot's name and icon the same way; in production the thread's status message names the environment in its footer.
Messages to a shop's own Slack¶
NotificationService.sendMessageAs(...) posts into a shop's workspace with the shop's own token
(fulfilment notices). These carry no Badger environment, bot icon or footer: which Badger
environment sent the message is no concern of the shop's.