Card and key
Production alerts change state: they fire, someone acknowledges, they resolve. If every notice were its own message, the channel would drown. With a key, GGspeak keeps the whole story on one card.
{ "key": "incident-123", "card": { "title": "API is down", "state": "alert", "body": "Timeout on /healthz" }}Send the same key with "state": "ok" and the card flips to “resolved in 3 min”. Its timeline reads: fired 14:02 · resolved 14:05.
How the key works
Section titled “How the key works”With a key, the API looks for the most recent message from the same webhook with that key, created in the last 24 hours. Keys from different webhooks never mix.
| Before → after | Result |
|---|---|
| None (or older than 24 h) → anything | New message |
ok → alert |
New message: the problem is back |
| Any other case | Updates the card |
Why does ok → alert open a new message? So a fresh problem isn’t buried in an old card, and because a new message calls the role again (Calling a role).
What an update changes
Section titled “What an update changes”- Title, body, fields and link become the ones that just arrived.
- The same state again bumps the card’s counter (“3×”).
- A new state resets the counter and adds an entry to the timeline. The timeline keeps up to 10 entries; the oldest drops off.
- Arriving at
okshows how long the problem lasted on the state line: “resolved in 3 min”. - The role that was called stays the one from the first message.
Example: fire, repeat, resolve
Section titled “Example: fire, repeat, resolve”| Step | Arrives | What happens |
|---|---|---|
| 1 | key: "inc-1", alert |
New message, calls the role |
| 2 | key: "inc-1", alert |
Updates the card: “2×” |
| 3 | key: "inc-1", warn |
Updates it: a warning enters the timeline |
| 4 | key: "inc-1", ok |
Updates it: “resolved in 3 min” |
| 5 | key: "inc-1", alert |
New message, calls the role again |
| 6 | key: "inc-2", alert |
Different key, new message |
Two POSTs with the same key at the same time end up as a single card.
When there is no key
Section titled “When there is no key”Without a key, every POST is a new message. That’s the case for Discord and Slack bodies, which have no such idea. Better Stack uses the incident id as the key automatically.
To update a message another way, use its id with PATCH: see Messages.
States and looks
Section titled “States and looks”| State | Word on the card | Use it for |
|---|---|---|
alert |
Firing | Something broke and someone should look |
warn |
Warning | Something needs attention, or someone acknowledged the incident |
ok |
Resolved | Back to normal, or a deploy went fine |
info |
Info | A notice with no urgency |
State is always shown with an icon and a word, never by color alone. The color comes from the app’s theme.