Referência do payload

Referência completa do endpoint de ingestão: cabeçalhos, campos do corpo, resposta e códigos de erro. Serve para quem está escrevendo o script ou configurando a ferramenta que vai enviar alertas para uma Fonte de Dados.

Endpoint

URL completa: https://app.flowbix.com/api/v1/alerts. A mesma URL atende todas as fontes de todas as empresas; o que identifica a sua fonte é o token.

O corpo é um objeto JSON de até 256 KiB. Corpo maior é recusado com 400.

Campos do corpo

O payload não tem campo de empresa, de fonte nem de id de evento: os dois primeiros vêm do token e o terceiro é gerado pelo servidor. Você só descreve o problema.

Espaços no início e no fim de key, host, title e comment são removidos. Campos desconhecidos são ignorados.

Mapeamento de severidade

Resposta

Alerta aceito responde 202 Accepted. O corpo diz o que vai acontecer com o alerta:

{
  "success": true,
  "status": "new",
  "key": "disco-cheio",
  "recurrence_count": 1
}

Valores de status na resposta

Erros

Retentativa e idempotência

Reenviar um problema com key é seguro: se o incidente já está ativo, o reenvio só atualiza os campos (active). Reenviar uma resolução também é seguro: se já estava resolvido, nada muda. Por isso trate 503, 500 e falhas de rede com nova tentativa, de preferência com espera crescente. Já um alerta sem key gera uma linha nova a cada POST, então reenviar cria duplicata.

Horários

O payload não tem campo de data. O servidor carimba o momento em que recebeu o evento, em UTC, e é esse horário que alimenta Duração atual e o histórico. Um alerta enviado com atraso aparece com a hora da chegada, não a do fato.

Exemplos com curl

Abrir um problema:

curl -sS -X POST https://app.flowbix.com/api/v1/alerts \
  -H "Authorization: Bearer whk_SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "disco-cheio",
    "host": "SRV-WEB-01",
    "title": "Disco / acima de 90%",
    "severity": 4,
    "message": "Uso em 92% — limpar /var/log",
    "status": "problem"
  }'

Fechar o mesmo problema (só a key e o host importam):

curl -sS -X POST https://app.flowbix.com/api/v1/alerts \
  -H "Authorization: Bearer whk_SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"key": "disco-cheio", "host": "SRV-WEB-01", "status": "resolved"}'

Alerta avulso, sem key (não agrupa nem resolve; só sai da lista com Descartar alerta):

curl -sS -X POST https://app.flowbix.com/api/v1/alerts \
  -H "Authorization: Bearer whk_SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"host": "backup-01", "title": "Backup noturno falhou", "severity": 3}'

Resposta esperada do último exemplo: {"success":true,"status":"new","key":null}.

Veja também

• Ciclo de vida do alerta e a key
• Exemplos de integração
• Descartar alertas de webhook
• Autenticação, erros e limites da API