Cartão e key

Alerta de produção costuma mudar de estado: dispara, alguém reconhece, resolve. Se cada aviso fosse uma mensagem, o canal ficaria cheio. Com a key, o GGspeak guarda tudo num cartão só.

{
  "key": "incidente-123",
  "card": { "title": "API fora do ar", "state": "alert", "body": "Timeout em /healthz" }
}

Mande a mesma key com "state": "ok" e o cartão passa a “Resolvido em 3 min”. A linha do tempo dele fica “Disparou 14:02 · Resolvido 14:05”.

Como a key funciona

Com key, a API procura a mensagem mais recente do mesmo webhook com essa chave, criada nas últimas 24 horas. Chaves de webhooks diferentes não se misturam.

Antes → depois	Resultado
Nenhuma (ou mais velha que 24 h) → qualquer	Mensagem nova
`ok` → `alert`	Mensagem nova: o problema voltou
Qualquer outro caso	Atualiza o cartão

Por que ok → alert abre uma mensagem nova? Para um problema novo não ficar escondido num cartão antigo, e porque a mensagem nova chama o cargo de novo (Chamar um cargo).

O que muda numa atualização

Título, corpo, campos e link passam a ser os do que acabou de chegar.
Mesmo estado de novo soma o contador do cartão (“3×”).
Estado novo zera o contador e entra na linha do tempo. A linha guarda até 10 entradas; a mais velha sai.
A chegada em ok mostra quanto o problema durou na linha de estado: “Resolvido em 3 min”.
O cargo chamado continua o da primeira mensagem: “Chamou @equipe”.

Exemplo: disparar, repetir, resolver

Ordem	Chega	O que acontece
1	`key: "inc-1"`, `alert`	Mensagem nova, chama o cargo
2	`key: "inc-1"`, `alert`	Atualiza o cartão: “2×”
3	`key: "inc-1"`, `warn`	Atualiza: entra “Aviso” na linha do tempo
4	`key: "inc-1"`, `ok`	Atualiza: “Resolvido em 3 min”
5	`key: "inc-1"`, `alert`	Mensagem nova, chama o cargo de novo
6	`key: "inc-2"`, `alert`	Outra chave, outra mensagem nova

Dois POSTs com a mesma key ao mesmo tempo resultam em um cartão só.

Quando não há key

Sem key, cada POST é uma mensagem nova. É o caso do Discord e do Slack, que não têm essa ideia. O Better Stack usa o id do incidente como key automaticamente.

Para atualizar uma mensagem por outro caminho, use o id dela com PATCH: veja Mensagens.

Estados e aparência

Estado	Palavra no cartão	Quando usar
`alert`	Disparou	Algo quebrou e alguém precisa olhar
`warn`	Aviso	Algo pede atenção, ou alguém reconheceu o incidente
`ok`	Resolvido	Voltou ao normal, ou um deploy deu certo
`info`	Info	Aviso sem urgência

O estado se mostra sempre com ícone e palavra, nunca só pela cor. A cor vem do tema do app.