On this page
Right people, not more people.
Many companies with more than a handful of services have a channel like #api-changes. Producer teams post there before a breaking change. It is the responsible thing to do, and it is what most of us were taught: announce early, announce widely.
Widely is the problem. An announcement is written for everyone, so it is read as if it were for no one in particular. The goal was never to tell many people. It was to tell the few whose code breaks.
Why the announcement channel feels right
- It is cheap. One post, no list to keep, no need to know who your consumers are.
- It is visible. Anyone can scroll back and see what changed.
- It covers you. After the incident, you can point at the post. “We announced it.”
The last one is the honest reason. An announcement channel protects the sender. It does very little for the reader.
Why it stops working
12 teams post in #api-changes
2 posts each a week → 24 posts
you call endpoints of 2 teams
some of their posts touch them
→ 1 or 2 of 24 posts are yours- People learn to skim, then to mute. When 22 of 24 posts are not about you, ignoring the channel is the rational choice. The one post that was about you goes with them.
- The reader has to do the matching. Every post asks every reader: do we call this endpoint? Most people cannot answer that from memory, so they guess.
- The team that needed it is often not there. A new team, a team in another office, the contractor team that built the mobile app: nobody added them to the channel.
- Posted is not received. The sender cannot tell who read it, so “we announced it” and “they knew” become the same sentence in the postmortem.
- Mentions make it worse.
@hereand@channelwake everyone up to tell a few. Slack itself asks for confirmation before one goes to a channel of six or more people, and lets owners restrict who may use them.
Telling is the sender’s job
An announcement moves the work to the reader: they must read everything to find what is theirs. A targeted message keeps the work with the sender, who knows what changed, and with a list of who calls each endpoint, which nobody can keep in their head.
That list is the hard part, and it is why the shared channel survives. If you do not know who calls GET /orders/{id}, posting to everyone is the only way to reach them. So the fix is not a better channel. It is knowing your consumers.
What to do instead
| Instead of | Do this |
|---|---|
| One channel for every change | A message in the channel each consuming team already reads |
| Every team reads every post | Each team gets only the endpoints it calls |
| The sender guesses who is affected | Consumer teams declare the endpoints they call, once |
@here to get attention | A small audience that reads because every message is theirs |
| Posting after the merge | Telling them while the change is still a pull request |
| A post per update | One message per change, updated as it moves |
The how-to for that message, what it should say and how to wire it into Slack and Microsoft Teams, is in API change notifications in Slack and Microsoft Teams.
Where Graphwake fits
Graphwake is built on this opinion. Consumer teams subscribe to the endpoints they call, and a breaking change in your OpenAPI spec reaches only those teams, in the Slack, Microsoft Teams or email channel each one picked. Everyone else hears nothing, apart from a one-time note to a team Discovery strongly suspects is a caller, and that silence is on purpose.
Subscriptions, not guesses
Each consumer team marks the endpoints it calls. The list stays current because the readers keep it.
Their own channel
Each team picks one Slack or Microsoft Teams channel, or email. Graphwake never adds
@hereor@channel.Before the merge
With the CI step, the alert goes out while the change is a pull request, and the same message is updated when it merges or closes.
Blind spots, not silence
An endpoint nobody subscribes to counts toward the impact score. Discovery suggests teams that may use it, and a team suggested at 60% or more gets a one-time “This may affect you” note when a breaking change goes live.
When a shared channel alone is enough
- A small company. If every engineer touches every service and there are a few changes a month, one channel is the targeted channel.
- As a record, not an alert. A feed of every change that nobody is expected to act on is a useful log.
- Public APIs. Customers outside your company are not in your Slack; a changelog and an email list reach them.
Questions
Is an #api-changes channel a bad idea?
As a record, no. As the way consumers find out about breaking changes, yes: each reader cares about a small share of the posts, so people mute it, and the team that needed one post misses it.
How do I know which teams to tell?
Ask the consumer teams to declare the endpoints they call, and keep that list where the alert can use it. Code search and gateway logs help you start; each misses callers the other finds.
Should API change alerts use @here or @channel?
No. If the message reaches only the teams that call the endpoint, it does not need a mention to be read.
Does Graphwake post to a shared channel?
Only if a team picks one. Each team chooses its own channel, and an alert goes only to the teams subscribed to the changed endpoint, plus a one-time note to teams Discovery suggests strongly.
Pick an endpoint. See who it reaches. 7-day free trial. Cancel before day 7 and you pay nothing.
Start free trialSources and last verified
- slack.com/help/articles/202009646-Notify-a-channel-or-workspace
- slack.com/help/articles/360004635551-Manage-channel-posting-permissions-
Sources checked on 2026-11-09.