Skip to content

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(...) and sendAdminMessageWithJson(...) (SlackNotificationService) put a SlackRequest on the queue and the worker's SlackNotificationServiceListener posts 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. StripeSlackClient posts 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.