Ciclo de vida do alerta e a key

A key é o que transforma uma sequência de POSTs em um incidente com história: ela agrupa ocorrências, conta recorrências e permite fechar e reabrir. Esta página explica como o Sentrya trata um alerta com e sem key e como escolher uma key boa.

Duas formas de chegar

O servidor gera um id de dedup para cada alerta que chega. A forma desse id depende de você ter mandado key:

	Com `key`	Sem `key`
Id interno	`k:` + a sua key (estável)	`o:` + valor aleatório (único por POST)
Repetir o envio	Cai no mesmo incidente e atualiza título, mensagem e severidade	Cria outro incidente, mesmo com texto idêntico
Recorrências (×N)	Contadas a cada reabertura	Não existem
`status: "resolved"`	Fecha o incidente da key	Recusado com `400`: não há o que fechar
Como sai da lista	Resolução enviada pela fonte, ou Resolver/Descartar alerta no app	Só com Resolver/Descartar alerta no app
Ouvinte	Pode ser ouvido pela key, por host ou pela Fonte inteira	Só pela Fonte inteira ou por host

Use alertas sem key só para avisos pontuais que não têm estado, como "deploy concluído com erro". Para tudo que pode voltar (disco, link, serviço parado), mande key.

O ciclo com key

A identidade do problema é fonte + host + key. O que acontece a cada POST depende do estado atual dessa identidade:

Estado atual	Você envia	Resultado	`status` na resposta
Nunca vista	`problem`	Cria o incidente, Recorrências = 1, notifica quem tem ouvinte	`new`
Ativo	`problem`	Atualiza título, mensagem, severidade e última ocorrência; não notifica	`active`
Ativo	`resolved`	Marca Resolvido, sai da lista de ativos; pode enviar aviso de resolução, se o ouvinte pedir	`resolved`
Resolvido	`problem`	Reabre o mesmo incidente: soma 1 em Recorrências, reinicia a Duração atual, zera o reconhecimento; pode notificar como recorrência	`recurrence`
Resolvido	`resolved`	Nada muda	`resolved`

Em forma de linha do tempo: new → active (repetições) → resolved → recurrence → active … O incidente nunca é apagado: resolver é uma mudança de estado, e a contagem de recorrências sobrevive a ela. Veja também Recorrências.

Título e mensagem podem variar sem quebrar a identidade. "Disco em 92%" hoje e "Disco em 95%" daqui a dez minutos são o mesmo problema se a key for a mesma. O card mostra sempre o texto do último envio. É por isso que a key fica fora de title e message.

Como escolher a key

Estável A key tem que ser idêntica em todos os envios do mesmo problema, inclusive na resolução. Nada de timestamp, contador ou id de execução.
Única dentro da fonte A linha do incidente é identificada por fonte + key. Se o mesmo check roda em vários hosts, coloque o host na key (disco-cheio:SRV-WEB-01) ou use uma key por host. Duas máquinas mandando disco-cheio puro para a mesma fonte disputam o mesmo incidente.
Legível A key aparece para quem monta um ouvinte e pode ser digitada à mão no wizard. link-fibra-caiu é melhor que um hash.
Curta Até 255 caracteres. Um padrão que funciona é host:check ou sistema/check.
Mesmo host nos dois lados Envie o mesmo host no problema e na resolução. A contagem de recorrência é por host + key.

Ações no app sobre alertas de webhook

Um incidente vindo de webhook não tem um Zabbix atrás dele, então as ações do app agem só no Sentrya:

Ação	Onde	O que faz
Reconhecer (ACK)	Detalhe do incidente e seleção em lote	Marca como reconhecido, grava comentário e pode mudar a severidade no Histórico de ACKs. Nunca fecha o incidente: a opção Fechar problema é recusada para webhook. Uma recorrência zera o reconhecimento.
Resolver	Seleção em lote na aba Incidentes	Marca os selecionados como Resolvido. Se a key voltar, conta como recorrência.
Descartar alerta	Detalhe do incidente	Mesmo efeito de Resolver, para um incidente só. É a única saída de um alerta sem key.

Só Admin e Operador executam essas ações; o Visualizador apenas lê. Detalhes em Reconhecer, fechar e comentar (ACK) e Descartar alertas de webhook.

Use comment para deixar rastro. Quando o seu sistema atualizar um problema aberto (por exemplo, "runbook X executado automaticamente"), mande o texto em comment. Ele entra no Histórico de ACKs do incidente com autor webhook, sem alterar o estado. Em resoluções o campo é ignorado.

A key e o ouvinte

O ouvinte de webhook casa alertas pela key e pelo host. Ao criar um ouvinte, o wizard lista os alertas já vistos da fonte, agrupados por key e host, com a contagem de vezes que chegaram; você marca os que quer ouvir. Se a fonte ainda não recebeu o alerta, use Adicionar key manualmente e digite a key exatamente como o seu script envia; o ouvinte vale para qualquer host. Fonte inteira cobre qualquer alerta da fonte, inclusive os sem key.

Isso tem uma consequência direta: uma key com timestamp nunca casa com um ouvinte, porque cada envio é uma key nova. E um ouvinte com urgência Sirene sobre uma key exige que o problema chegue com severity: 5; envios abaixo disso são recusados com 422. Veja Sirene: o alerta máximo.